Common Lisp Interface Manager (CLIM) 



PREFACE 

This book documents how to develop programs using the Common Lisp Interface 
Manager (CLIM), Release 2.0. It is intended for use by programmers who are expe- 
rienced with Common Lisp and CLOS programming concepts. 

This book is useful for a programmer writing CLIM 2.0 applications on any Lisp 
platform, but includes some material that is specific to CLIM on Genera and Cloe. 

Organization 

This document has these major parts: 

"What is CLIM?" Describes the roots of CLIM 2.0, gives a technical 

overview of it, and compares it to Genera's Dynamic Win- 
dows. 

"CLIM Tutorial" Gets you started developing programs in CLIM with ex- 

tended examples that you can run. This section introduces 
the important concepts of CLIM via these examples. 

"CLIM User's Guide" Provides concept-oriented reference documentation cover- 
ing topics in more detail than the Tutorial. The chapters 
in the User's Guide also include summaries of functions, 
classes, macros, etc., which are documented more fully in 
the Dictionary. 

"CLIM Dictionary" Provides detailed reference documentation of CLIM func- 

tions, classes, macros, and so forth, in alphabetic order. 
You can use the CLIM Dictionary when you need to know 
the syntax and semantics of a particular CLIM operator. 

"Glossary of CLIM Terminology" 

Provides a description of many CLIM terms. 

How to Use This Book 

Start with "What is CLIM?" for background information and a technical overview 
of CLIM. 

When you are ready to start programming, proceed to the "CLIM Tutorial", and 
experiment with the examples. Code for these examples can be found in the direc- 
tory SYS: CLIM; REL-2; TUTORIAL;. The directory SYS: CLIM; REL-2; DEMO; is also a rich 
source of example code. 

When you want to learn about a topic in more detail, you can use the "CLIM 
User's Guide" and the "CLIM Dictionary"). 
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Documentation Conventions 

This documentation uses the following notation conventions: 

Printed representation of Lisp objects in running text. 

Keys on the keyboard. 

The space bar. 

Literal typein. 

Lisp code examples. 



cond, climraccept 

Return, Rbort, control -F 

SPRCE or Space 

login 

(make-symbol "foo") 



(my-find item list &optional test &key .start send) 

Syntax description of the invocation of the function 
my-find. 



item, list, test 

.start, send 
&optional, &key 
Show File, Start 



Arguments to the function my-find, usually expressed 
as a word that reflects the type of argument (for ex- 
ample, string). 

Keyword arguments to the function my-find. 

Introduces optional or keyword argument(s). 

Command processor command names appear with the 
initial letter of each word capitalized. 



m-X Insert File, Insert File (m-X) 

Extended command names in Zmacs, Zmail, and Sym- 
bolics Concordia appear with the m-K notation either 
preceding the command name, or following it in 
parentheses. Both versions mean press m-K and then 
type the command name. 



[Map Over] 

Left, Middle, Right 
shift-Right, c-n-Middle 



Menu items. Click Left to select a menu item, unless 
other operations are indicated. (See the section 
"Mouse Command Conventions".) 

Pointer gestures (also known as mouse clicks). 

Modified mouse clicks. For example, shift-Right 
means hold down the SHIFT key while clicking Right 
on the mouse, and c-n-Middle means hold down the 
CONTROL and METR keys while clicking Middle. 



Modifier Key Conventions 

Modifier keys are designed to be held down while pressing other keys. They do not 
themselves transmit characters. A combined keystroke like Meta-K is pronounced 
"meta x" and written as m-K. This notation means that you press the METR key and, 
while holding it down, press the K key. 

Modifier keys are abbreviated as follows: 
CONTROL c- or control- 
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METR 


n- or meta- 


SUPER 


s- or super- 


HYPER 


h- or hyper- 


SHIFT 


sh- or shift 



These modifier key names are based on the labels on a Symbolics keyboard, and 
most keyboards do not label their modifier key names the same way. This is just a 
convention; non-Symbolics machines will simply use differently labelled keys on the 
keyboard. 

Modifier keys can be used in combination, as well as singly. For example, the nota- 
tion c-n-Y indicates that you should hold down both the CONTROL and the METR 
keys while pressing Y. 

Modifier keys can also be used, both singly and in combination, to modify mouse 
commands. For example, the notation sh-Left means hold down the SHIFT key 
while clicking Left on the mouse and c-n-Middle means hold down CONTROL and 
METR while clicking Middle. 

The keys with white lettering (like H or SELECT) all transmit characters. Combina- 
tions of these keys should be pressed in sequence, one after the other (for exam- 
ple, SELECT L). This notation means that you press the SELECT key, release it, and 
then press the L key. 



Trademarks 

CLIM is a registered trademark of International Lisp Associates (ILA). Microsoft 
and MS-DOS are registered trademarks of Microsoft Corporation. Windows, 
Windows/286 and Windows/386 are trademarks of Microsoft Corporation. Intel and 
386 are trademarks of Intel Corporation. Adobe and PostScript are registered 
trademarks of Adobe Systems Inc. 



What is CLIM? 



Technical Overview of CLIM 

CLIM is an acronym for the Common Lisp Interface Manager. It is a portable, 
powerful, high-level user interface management system toolkit intended for Com- 
mon Lisp software developers. The important things to understand about CLIM 
are: 

• How it helps you achieve a portable user interface — how it fits into an existing 
host system; how you can achieve the look and feel of the target host system 
without implementing it directly, and without using the low-level implementa- 
tion language of the host system. 

• The power inherent in its presentation model — the advantages of having the vi- 
sual representation of an object linked directly to its semantics. 
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• The set of high-level programming techniques it provides — capabilities that en- 
able you to develop a user interface conveniently, including formatted output, 
graphics, windowing, and commands that are invoked by typing text or clicking 
a mouse (or "pointer") button, among other techniques. 

CLIM 2.0 does not currently provide any high-level user interface building tools, 
nor does it provide any sort of high-level graphical or text editing substrate. These 
are areas into which future releases of CLIM may extend. 

CLIM is also not suitable for high performance, very high quality graphics of the 
sort needed for sophisticated paint, animation, or video postproduction applications. 
Of course, it is possible to write the bulk of such an application's user interface 
using CLIM, and use lower level facilities for drawing in the main "canvas" of the 
application. 



Introduction to CLIM's Presentation Model 

A software application typically needs to interact with the person using it. The 
user interface is responsible for managing the interaction between the user and 
the application program. The user interface gets information from the user (com- 
mands, which might be entered by typing text or by clicking a mouse), gives that 
information to the application, and later presents information (the program's re- 
sults) to the user. Figure 25 shows this common paradigm. 
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Figure 46. Cycle of Input/Computation/Output 

We might describe one conventional approach to the input/computation/output cycle 
as follows. Invisibly to the user, the application takes the commands and interprets 
them in terms the program can handle. For example, if the application uses object- 
oriented techniques, it might build objects based on information garnered from the 
command and arguments, then manipulate those objects internally, finish its com- 
putation, and finally translate from the resulting objects to the appropriate re- 
sponse which is then given to the user. Figure 26 depicts this sequence of events. 

The conventional approach uses object-oriented techniques within the computation 
phase, but the objects do not surface to the user interface. The program performs 
two translations: from user input to objects, and later from objects to output in- 
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User enters command and arguments 



Program 


interprets command and arguments 


Program 


builds objects based on commands 


Program 


manipulates its internal objects 


Program 


translates objects to visible results 


Program 


discards objects 



User sees results of the program 



Figure 47. Conventional Approach to the Input/Computation/Output Cycle 

tended for the user. CLIM revolutionizes the cycle by bringing the power of object- 
oriented programming to the surface, all the way up to the user interface. 

CLIM recognizes that many applications manipulate internal objects which we call 
application objects and they have display objects, which are presented to the user. 
A display object can appear as text or a graphic picture. CLIM supports a direct 
linking between application objects and display objects. CLIM automatically main- 
tains the association between application objects and display objects, so there is no 
need for the application to do any translation. Figure 27 shows how CLIM views 
the cycle of input/computation/output. 

In effect, CLIM replaces some of the tedious and error-prone steps of the conven- 
tional user-interface model with higher-level object-oriented techniques. The advan- 
tages of the object-oriented user interface are subtle but extremely powerful (in 
fact, you might not recognize them at first glance, but they will grow on you grad- 
ually as you develop your CLIM applications): 

• A command is structured so that the user interface understands something of 
the semantics of its arguments. That is, each argument must be an object of a 
specified type. This helps the user in several ways: 

° The user is prevented from entering invalid input, because the user interface 
automatically enforces the validity of each argument. 

° The user can get online help or prompting from the user interface, based on 
the type of the argument. 

° The user can enter input in creative and convenient ways, such as by clicking 
on object displayed on the screen by a previous command. The user interface 
knows which displayed objects are valid within the current context, and can 
make them sensitive (the objects are highlighted as the pointer passes over 
them). 
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*The command and arguments can also come from a single gesture. 



Figure 48. CLIM Approach to the Input/Computation/Output Cycle 



° The user has a flexible means of interacting with the application, and often 
can choose whether to use the mouse or keyboard to communicate with the 
application. 

• In CLIM, the user interface directly reflects the application's structure, because 
the display objects stand for application objects. Unlike the conventional model, 
a CLIM user interface is not tacked on the application as a separate entity 
which can diverge from the application to ill effect. CLIM's direct linking be- 
tween the application and display objects ensures a natural consistency between 
the application and its user interface. 

• Display objects are organized in a type lattice in the usual object-oriented way, 
so inheritance can be used to good advantage. For example, when the user is 
entering an argument of a given type, objects of that type and its subtypes are 
valid as input. For example, an application might define display objects repre- 
senting buildings, schools, and houses. When the application needs a building as 
input, the user can enter a school, because school is a subtype of building. 
CLIM also offers a library of predefined types, saving the application program- 
mer some effort when dealing with commonly used display types. 

• Objects can be shared freely among different applications. CLIM's ability to 
share objects directly contrasts to some conventional systems, in which data can 
be shared among applications only by reducing it to its lowest common denomi- 
nator (usually text). 
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How CLIM Helps You Achieve a Portable User Interface 

CLIM provides a consistent stream-oriented interface to window systems across a 
large set of hosts. When developing a portable user interface, you write your appli- 
cation in terms of CLIM windows and their operations. You can also use Common 
Lisp and CLOS. Figure 28 shows the elements on which your application depends. 



f Portable application J 



( CLIM J 



Common Lisp 
CLOS 



Figure 49. Foundation of a Portable Application 



Your application is portable because it depends only on languages which have been 
standardized: Common Lisp, CLOS, and CLIM. Of course, porting is never entirely 
effortless, because different implementations of standardized languages can differ 
from one another in minor ways. 

From the perspective of your application, the details of the host window system, 
host operating system, and host computer should be invisible. CLIM handles the 
interaction with the underlying window system. Figure 29 shows the elements of 
the host system from which CLIM shields your application. 

CLIM shields you from the details of any one window system by abstracting out 
the concepts that many window systems have in common. Using CLIM, you specify 
the appearance of your application's output in general, high-level terms. CLIM 
turns your high-level description into the appropriate appearance for a given win- 
dow system. 

In some cases, you might prefer to control the appearance of your user interface 
more directly. You can bypass CLIM and use functions provided in the underlying 
window system or toolkit to achieve more explicit control, at the expense of porta- 
bility. 



Highlights of CLIM Tools and Techniques 

CLIM offers the following tools and techniques: 

Windows and events 

A portable layer for implementing sheet classes (types of win- 
dow-like objects) that are suited to support particular high lev- 
el facilities or interfaces. The windowing module of CLIM de- 
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Figure 50. How CLIM is Layered Over the Host System 



Graphics 



Output recording 



Formatted output 



fines a uniform interface for creating and managing hierar- 
chies of these objects regardless of their sheet class. This layer 
also provides event management. 

A rich set of drawing operations, including complex geometric 
shapes, a wide variety of drawing options (such as line thick- 
ness), and a sophisticated color inking model. CLIM provides 
full affine transforms, so that you can perform arbitrary trans- 
lations, rotations, and scaling of drawings. 

A facility for capturing all output done to a stream, which pro- 
vides the automatic support for scrollable windows. In many 
cases, programs produce output in the form of display objects, 
which can be manipulated directly by the user (see context- 
sensitive input). Thus, not only is the output recorded — 
whether textual or graphic — but it also retains its semantics 
and can be reused when appropriate. 

High-level macros that enable you to produce neatly formatted 
tabular and graphical displays with minimal effort. 



Context-sensitive input 

Simple, direct means of using a displayed output object as in- 
put. As mentioned above, an application can produce output via 
objects, which retain their semantics. Users can recycle visible 
output into input for the same application or a different one. 
Each CLIM application sets up a context for what kind of in- 
put is expected at a given time. For example, a CAD program 
that supports designing electrical circuits might have a com- 
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mand called Set Resistance which sets up an input context in 
which a resistor object is expected. Any resistors appearing in 
the CAD programs display are automatically made mouse- 
sensitive in that context, so the user can click on one to enter 
it as input. 

Adaptive toolkit A uniform interface to the standard compositional toolkits 
available in many environments. CLIM defines abstract panes 
that are analogous to the gadgets or widgets of a toolkit like 
Motif or OpenLook. CLIM fosters look and feel independence 
by specifying the interface of these abstract panes in terms of 
their function and not in terms of the details of their appear- 
ance or operation. If an application uses these interfaces, its 
user interface will adapt to use whatever toolkit is available in 
the host environment. By using this facility, application pro- 
grammers can easily construct applications that will automati- 
cally conform to a variety of user interface standards. In addi- 
tion, a portable CLIM-based implementation of the abstract 
panes is provided. 

Application-building facilities 

High-level facilities for defining applications, helping you to lay 
out windows and gadgets, manage command menus and menu 
bars, and link user interface gestures (such as mouse clicks) 
with application operations. The application-building tools help 
you construct a flexible user interface that can grow from the 
protototype to the delivery phase. 



Comparing and Contrasting DW and CLIM 

This section describes CLIM in terms of how it is similar to and how it differs 
from Dynamic Windows. It also discusses conversion issues. 

CLIM offers some advantages over Dynamic Windows. In brief, these are: 

• Ability to develop a portable user interface. 

• Support for using toolkits offered on various window systems to achieve the 
look-and-feel of a given system. 

• Simplification of some Dynamic Windows functionality, resulting in greater ease 
of use and superior performance. 

• Exposed underlying protocols, enabling you to modify or extend the behavior of 
CLIM. 

Converting an Application From DW to CLIM 

Genera users do not have to convert programs from Dynamic Windows to CLIM. 
Symbolics will continue to support DW in Genera. In fact, it is possible that the 
portions of Genera that use Dynamic Windows will not be reimplemented in CLIM. 
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One good reason to convert an existing program to CLIM is to take advantage of 
the portability benefit that CLIM provides. If your goal is to deliver an application 
with a user interface on a variety of Lisp platforms with different window systems, 
you will probably want to convert the application's user interface to CLIM. 

Another good reason to convert a Dynamic Windows program to CLIM is that 
many of the high level facilities in CLIM are faster than in Dynamic Windows. 

Symbolics provides a conversion tool to help automate the procedure of converting 
programs from DW to CLIM. For more information, see the section "Converting 
from Dynamic Windows to CLIM". 

When developing a new application, you will need to decide whether the user in- 
terface should be programmed in Dynamic Windows or CLIM. Although both will 
coexist in Genera, there is no direct compatibility between them, and hence no 
mixed programming approach. 



Converting an Application From TV to CLIM 

Some Genera users have applications that depend on Release 6 window functions 
in the tv package. In some cases, these applications were not converted to Dynam- 
ic Windows because of performance reasons. CLIM's performance is superior to 
that of Dynamic Windows, so for performance reasons, users may want to convert 
programs that use Release 6 window functions to CLIM. 

Note that the Release 6 window system has a very different architecture from DW 
or CLIM. For example, window programs typically define new flavors of the win- 
dow with methods that handle very low-level events (such as refresh and mouse 
motion). Because of this architectural difference, converting from tv to CLIM usu- 
ally requires a careful redesign of an application's user interface, and the useful- 
ness of automatic conversion tools is limited. 



Similarities Between Dynamic Windows and CLIM 

• CLIM supports essentially the same presentation model as that in Dynamic 
Windows. CLIM captures the Dynamic Windows' philosophy that a program's 
user interface should reflect its semantics. 

• CLIM provides a graphics model which is similar to that of Dynamic Windows, 
but is simplified and more uniform. 

• CLIM includes an application-building tool similar to the dwrdefine-program- 
framework of Dynamic Windows. 

• CLIM's command processor is virtually identical to that of Dynamic Windows. 

• CLIM's input editor is a simplification of that of Dynamic Windows. 

• CLIM supports a version of Genera's character styles. In Dynamic Windows 
characters, strings, and displayed text have style. In CLIM only displayed text 
has style. 
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CLIM supports completion and context-sensitive help in the spirit of Dynamic 
Windows. 



CLIM as a UIMS, and Not a Window System 

Dynamic Windows plays two distinct roles. It is both a window system and a user 
interface management system. CLIM is not a window system; it is layered on top 
of some other window system, such as X, NeWS, or Microsoft Windows. Therefore, 
CLIM recasts the interfaces of Dynamic Windows related to being a window sys- 
tem in a portable manner. CLIM encompasses the functionality of many window 
systems; it acts as an "abstract window system" or a "generic window system" 
which can be layered on top of another window system. CLIM enables you to devel- 
op a portable user interface, whereas Dynamic Windows does not. 

The portions of Dynamic Windows that are directly related to its role as a window 
system are not included in CLIM. For example, in Dynamic Windows, you can op- 
erate on a window by sending it a message because some dynamic windows are im- 
plemented as flavors that use the message-sending paradigm. CLIM does not sup- 
port that paradigm. 

CLIM, like the second role of Dynamic Windows, is a user interface management 
system. CLIM shares the philosophy that you as programmer should be able to ex- 
press what you want to do in high-level terms, and the system should manage the 
details for you. 



CLIM is Built up From Layered Protocols 

Whereas Dynamic Windows includes a great deal of flexibility in its single docu- 
mented interface, CLIM is a layered protocol in the spirit of CLOS. In this docu- 
ment, we refer to the higher level as the CLIM Application Programmer Interface 
(or API) and the underlying level as the CLIM Class Protocol. 



CLIM Programmer Interface 



CLIM Class Protocol 



Figure 51. CLIM Protocol Layers 



At the API level, an important design goal is that there should be one simple way 
to do something. There can be some exceptions to this goal; when a very common 
idiom is identified, it might be included even if there is another (more verbose) 
way to do the same thing. Where some Dynamic Windows functions and macros of- 
fer many keyword arguments, CLIM pares these down to a minimal set without 
sacrificing functionality. 
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The CLIM Class Protocol is exposed to allow advanced users to modify or extend 
CLIM in the object-oriented way. The API functions and macros are implemented 
in terms of the CLIM Class Protocol. The CLIM Class Protocol, for the most part, 
is not documented in this book. If you are interested in the CLIM Class Protocol, 
you should consult the CLIM II Specification. 



Comparing the Presentation Type Systems 

Dynamic Windows allows the presentation type lattice to be computed at run-time. 
In Dynamic Windows, using inheritance can get complicated, because you must 
specify what happens at run-time. In CLIM, the type lattice is fixed at load-time, 
as it is in CLOS. By fixing the type lattice at load-time, CLIM achieves a perfor- 
mance improvement and simplifies the conceptual model. In practice, this restric- 
tion has had no negative effects on any applications, and has the benefit of making 
CLIM's presentation type system far faster than the Dynamic Windows presenta- 
tion type system. 

The CLIM presentation type system is a straightforward extension of the CLOS 
type system. In CLIM, defining a presentation type is similar to defining a CLOS 
class. CLIM extends the CLOS type system by supporting parameterized types, 
such as integer ranges. This has the benefit of making the CLIM presentation type 
system "feel" almost exactly like CLOS. 



CLIM's Unified Geometric Model 

CLIM includes a unified geometric model which is used to represent windows, 
graphics, and widgets. In other words, everything from a window itself to the 
graphics drawn on it conforms to the same geometric model. This enables you to 
deal with windows and graphics in a uniform way. CLIM also provides a general 
model for transforming, rotating, and scaling geometric objects. CLIM's unified ge- 
ometric model results in a simplification of some mechanisms used in Dynamic 
Windows. 



CLIM and User Interface Appearance 

It is an ambitious goal of CLIM to bridge a wide gap between two styles of user 
interface programming. 

In Genera's style, the principal goal is for the user interface to convey the appli- 
cation's semantics. This goal leads to a natural consistency between the application 
and its user interface. However, Genera and Dynamic Windows have been weak in 
enabling programmers to specify a unique and attractive appearance of the user 
interface. In other words, Genera has tended to sacrifice form for content. 

Many commercial toolkits have powerful means of controlling the visual appear- 
ance of a user interface. Traditionally, these toolkits offer no support at all for 
connecting the application's semantics to its user interface. The user interface is 
thus designed and implemented as a separate, add-on piece to the application. In 
other words, the toolkits tend to sacrifice content for form. 
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What's missing from each of these approaches is the connection between the se- 
mantics and the appearance of a user interface. CLIM enables the programmer to 
specify the semantics and appearance of the user interface in an integrated way. It 
provides the glue between the two. 

For example, suppose that your user interface wants to use a dialog to read a real 
number in the range from zero to ten from the user. A conventional toolkit might 
make it easy to provide a visually attractive slider to prompt the user, but when 
the application receives the input, there are no semantics associated with it; the 
programmer must write some callback that handles events on the slider and con- 
verts them to the desired real number. In Genera, the straightforward way to get 
the number is to give a textual prompt such as "Enter a number from to 10". 
The appearance of the prompt is not particularly appealing, but when the input 
arrives, Genera knows its semantics; it is a real number in the correct range. 
CLIM aims to include the strength of each of these paradigms. The presentation 
model maintains the link between the application's semantics and its user inter- 
face. The adaptive toolkit enables you to provide a visually attractive user inter- 
face. So, if you want to use a slider to get a real number in the range from to 
10 from the user, you can use the following: 

(cl im:accept '((real 10)) :view cl im:+sl ider-view+) 



A Tutorial on the Common Lisp Interface Manager (CLIM) 



What is CLIM and Why Should I Learn About It? 

The CLIM user interface manager provides a novel way to connect input and out- 
put to the semantics of the application. It is not a window system but rather al- 
lows you to write portable applications that use the underlying window system 
and/or toolkit interface. 

This tutorial provides several examples of working code and then discuss the fea- 
tures of CLIM used in the code. While familiarity with Common Lisp programming 
is definitely a prerequisite for using CLIM, there is no need to be a "wizard" to 
read the examples. We have tried to shift the balance between simplicity and real- 
ism of the examples toward simplicity as much as possible. 

Many of the facilities described in this tutorial are not fully documented here; for 
full documentation we refer you to the "CLIM User's Guide" and the "Dictionary 
of CLIM Operators". The intent of the tutorial is to familiarize you with the basic 
use of the CLIM application-building facilities; this will prepare you to understand 
the reference documentation. 

Note for the advanced reader: Throughout this tutorial you will see text like this. This is an 
indication to you that the material contained here is meant for the more knowledgeable reader. 
The beginning reader is encouraged to skip this material; you will not lose any of the basic lesson 
of the tutorial. 

This tutorial simplifies a lot of material. The purpose of these notes is to warn the advanced 
reader against reading too much into the simplified description of certain CLIM features presented 
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in the tutorial. In cases where a particularly simplified version of CLIM functionality is presented, a 
note like this will follow, indicating what simplifications have been made. 



The Fifteen Puzzle — an Elementary Application 

This chapter and the following two chapters show the evolutionary development of 
an elementary CLIM application. While the example is simple and short, it illus- 
trates many of the features of a typical CLIM application. We present a series of 
complete, working programs. The programs can be short and yet complete because 
they make extensive use of high-level facilities provided by CLIM. 

For this first example application, we have chosen the famous "Fifteen Puzzle", a 
sliding block puzzle which dates back more than a century. [Ref: Sliding Piece 
Puzzles, Edward Hordern, Oxford University Press, 1986.] The Fifteen Puzzle con- 
sists of a 4 by 4 array of spaces, fifteen of which are filled by consecutively num- 
bered pieces. The remaining space is open, which allows a piece to slide into that 
space, effectively interchanging the piece and the space. Only pieces that are adja- 
cent (horizontally or vertically) to the space can move. 




What is an Application? 
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We have already used the term "application" in this tutorial. Now we will make 
the use of this term a little more specific. An application is a program that con- 
tains a user interface component that interacts directly with the user (as opposed 
to, say, a library). CLIM lets you build what it calls an application which is a 
Lisp object that encapsulates much of the information necessary for a program to 
run. 

Many applications fall into a simple framework: they consist of a "loop" doing 
three things, one after the other, repeatedly: 

Input Find out what to do; 

Process Do it; 

Output Show what happened. 

Chances are, many programs that you already know fall into this general scheme. 
Consider an editor, a Lisp listener, or a spreadsheet, and see if you can see how 
they can be regarded in this manner. 

Note for the advanced reader: Of course, many applications don't fall into this simple frame- 
work. (Examples are applications that employ multiple processes, or applications that deal with 
asynchronous input from another source as well as the user.) That doesn't mean you can't use 
CLIM to build those applications too. 




Figure 53. The Simple Application Loop. 



Now it's time to look at the first version of the Fifteen Puzzle application. If you 
are reading this tutorial on-line, or if you have access to a machine, read the file 
SYS:CLIM;REL-2;TUT0RIAL;PUZZLE-1 .LISP into an editor buffer. In case you don't 
have on-line access, see the section "Code for Puzzle-1". 

If you can do so, run the application right now. Read the file SYS: CLIM; REL- 
2; TUTORIAL; PUZZLE-1 .LISP into an editor buffer. Then do the following: 
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1. Compile the buffer. 

m-X Compile Buffer 



2. At the end of the file there are two or three forms commented out with #| 
and Itf. Evaluate those forms by marking them, wiping them, and yanking 
them into a Listener and pressing END, or by marking them and pressing 

c-sh-E. 

To exit from this first version of the puzzle, select the window in which you evalu- 
ated the clim:run-frame-top-level form. (This window should be visible immediate- 
ly behind the puzzle.) You will need to press RBORT or otherwise tell the process to 
stop executing the application's top-level. 




Figure 54. The First Version of the Fifteen Puzzle 



The application occupies a small amount of space on the screen and the space is 
divided into two pieces — a display of the puzzle, and a small menu at the bottom 
with four menu items: Down, Up, Left, and Right. The whole area is the applica- 
tion's top level sheet; because it is subdivided we call it a frame, and the two pieces 
are each called panes. 

Notice that the menu items highlight when the mouse points at them. This is 
CLIM's indication to you that something will happen when you click the mouse at 
that place. Try clicking the mouse on any of the four menu items. "Right" means 
"try to move a piece right into the space", and similarly for "Left", "Up", and 
"Down". 

The most important defining form is at the beginning of the source file. 

(cl im:def ine-appl ication-f rame f ifteen-puzzle-1 () 
((pieces :initform ...)) 
( : panes 

(display . . . ) 
(menu ...))) 
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clim:define-application-frame is used here to define a class of applications called 
f ifteen-puzzle-1. It is important to realize that this is the definition of the class, 
not the creation of a member of the class. 

CLIM is implemented using the Common Lisp Object System — CLOS for short. 
You don't have to know a lot about CLOS to use CLIM, but if you do know about 
CLOS you may find that you can apply that knowledge to writing CLIM programs. 

Note that the name "fifteen-puzzle-1" is used in some other places in the source 
file. You use the name of an application when making an instance of it or when 
you write a new command or method for it. (Defining commands for applications is 
discussed in the section "Application Commands".) 

To understand this program there are several other concepts that we must intro- 
duce. In the following sections we will discuss: 

• an application's state, 

• an application's commands, 

• the panes, or sub-windows that have already been mentioned, 

• and the display function associated with a pane. 



Application State 

A dictionary definition of state is "a mode or condition of being with respect to a 
set of circumstances". 

It is often useful for a program to remember things, even when the user is not 
running the program. Most operating systems let users switch their attention 
among several activities; users are more productive if they can return to a partly 
completed task and find the program's appearance and behavior reflecting the state 
of the task. 

The Fifteen Puzzle has state. If you put it aside, and later return to it, you expect 
the pieces to be where you left them. 

As the implementor of a program, you might choose to use global variables to 
store such state. Storing the state as part of the program itself is often a better 
choice than using global variables because: 

• you might want more than one copy of the program around — each copy needs 
its own state; 

• the values representing the state are less vulnerable to being inappropriately 
modified (for example, by another program in a shared Lisp environment); 

• access to the state can be more efficient. 

In short, we encourage the practice of storing state as part of the application ob- 
ject as good software engineering. 
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A CLIM application may contain state variables. State variables are CLOS slots. 
They are described in the clim:define-application-frame form in the same manner 
as slots are described in closrdefclass. For a full description of CLOS slots, see 
the section "Accessing Slots of CLOS Instances". 

A typical specification of an application state variable might include: 

• the name (mandatory), 

• an initial value, 

• reader, writer, or accessor functions, and 

• documentation. 

In the Fifteen Puzzle, we have a state variable called pieces which is an array 
containing the current arrangement of pieces in the puzzle. 



Application Commands 

In CLIM, a command is the way to tell an application what to do. A command is a 
lisp object with structure. It's important to think of a command as an object you 
(the user) may enter in several different ways. That's how CLIM supports mixed- 
mode interfaces where the user tells the application what to do in different ways. 

Commands may be entered by: 

• clicking on menu buttons 

• clicking on items displayed in the interface (when a piece of a display responds 
to the user clicking on it, we say the item is sensitive) 

• typing strings of characters (the facility that turns a string into a command is 
called a command parser) 

• typing individual characters that each represent a command (such characters 
are called keyboard accelerators, they are often "control" or "meta" characters 

• a combination of the above. 

When you define a CLIM application by using clim:define-application-frame, one 
of the results is the definition of a command-defining macro for your application. 
Since the application is called fifteen-puzzle-1, the macro that gets defined is 
named define-fifteen-puzzle-1-command. This is one of the results of naming the 
class of applications as discussed in "What is an Application?". 

Note for the advanced reader: You can override the name that CLIM chooses for the command- 
defining macro if you wish. You can also decline to have one created at all if you wish. 

Here is one of the commands of the Fifteen Puzzle: 

(define-f if teen-puzzle-1 -command (right :menu t) () 
(with-slots (pieces) cl im:*appl ication-f ramex 
(f ind-empty-piece-and-do (y x) 
(unless (zerop x) 

(rotatef (aref pieces y x) (aref pieces y (- x 1))))))) 
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When you write a command, you make the state variables of the application frame 
via clos:with-slots, since clim:*application-frame* will be bound to the application 
frame. In the Fifteen Puzzle command above, we refer to the variable pieces in 
just that way. 

The name of the command is right. The option :menu t says that we want this 
command to appear in the command menu for the application. 



Application Panes 

It is often useful to partition your application's screen-area into functional divi- 
sions. A menu is such a partition — it groups all the menu buttons into one area. 
A drawing program may have an area reserved for displaying small versions of 
saved drawings, or for iconic representations of drawing tools. By placing like 
things near each other, the application designer can make the interface easier to 
use. 

A pane is CLIM's name for a sub-window, that is, a window-like region within a 
window. The panes within a window form some configuration within a frame, and 
cannot be exposed or deexposed individually. 

CLIM lets you describe how you want your application's window partitioned into 
panes. There are two parts to the description of an application's panes: 

• describing each pane, individually; 

• and describing how the panes are laid out to occupy the space available. 

The description of an individual pane names the pane, and its type. The descrip- 
tion may also contain other options that apply to the pane, such as whether the 
pane has scroll bars. 

Descriptions of individual panes are introduced by the keyword rpanes in the 
defining form. In the Fifteen Puzzle, the pane descriptions look like this: 

(cl im:def ine-appl ication-f rame f ifteen-puzzle-1 () 

( : panes 

(display : application ...) 
(menu : command-menu ...))) 

Two panes are described, a pane named display and a pane named menu. Immedi- 
ately following the pane is a keyword that assigns the type of the pane. The two 
types of panes here are: 

• rapplication — a general purpose type of pane used for display; 

• :command-menu — a pane used for displaying a menu of commands. 

We will see other types of panes later. 

We will discuss pane layout later in the tutorial. The definition for the Fifteen 
Puzzle does not explicitly specify a layout, which means that CLIM will supply a 
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simple default layout. The default layout consists of stacking all the panes verti- 
cally, in the order that the panes are mentioned in the rpanes description. 



Application Output 

In the basic application loop that we discussed in "What is an Application?", one of 
the main functions that an application performed was to update the display to re- 
flect the changed internal state of the application. 

In the definition of the Fifteen Puzzle, there is a keyword : display-function in the 
pane description, followed by a name: draw-the-display. 

(cl im:def ine-appl i cat ion- frame f ifteen-puzzle-1 

( : panes 

(display : application 

:text-style '(:fix :bold :very-large) 
: di spl ay-f uncti on ' draw-the-di spl ay 
: scroll -bars nil) 

This is how you tell CLIM how to draw the display you want. Since CLIM is pro- 
viding the application loop itself, all you need to do is provide the name of a func- 
tion, and CLIM's default loop will call it after executing a command. 

Note for the advanced reader: CLIM offers many options for modifying this behavior. You 
choose whether the pane should be cleared first or not. You can decline the facility completely 
and call display functions yourself as part of your commands. You can employ more advanced 
features of CLIM to incrementally redisplay only those parts of the display that have changed. 

CLIM expects to call a function or method that takes two arguments: the applica- 
tion object and the stream on which the output should take place. Whatever func- 
tion you write must have the correct argument list. 

Here is the function that the Fifteen Puzzle uses for drawing the board. 

Note for the advanced reader: We have chosen to make the function a method on the applica- 
tion. This is a common choice in many circumstances: it may allow faster slot access to the 
application's state variables; it is also sometimes done to allow multiple classes of applications to 
share code — using, for example, :after methods. 

(def method draw-the-display ((application f ifteen-puzzle-1) stream 

&key &al low-other-keys) 
(with-slots (pieces) application 
(dotimes (y 4) 
(dotimes (x 4) 

(let ((piece (aref pieces y x))) 
(if (zerop piece) 

(format stream " ") 
(format stream "~2D " piece)))) 
(terpri stream)))) 
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Note that this function draws the entire display. In a later chapter, "Further De- 
velopment of the Fifteen Puzzle", we will see examples of how to draw part of the 
display, while leaving part of the display unchanged. 

Note also the use of &key and &allow-other-keys. This is because CLIM can pass 
addition keyword arguments (:max-width and :max-height) to display functions, so 
display functions must be prepared to handle them. 



Summary 

An application is a program that interacts with the user for a specific purpose. An 
application frame is an object that helps you implement an application. The con- 
tents of an application frame are specified by using clim:define-application-frame. 

Applications have state. You can store values representing pieces of state in an 
application's state variables. 

A command is an object that tells an application what to do. Commands can be en- 
tered in several different ways, including clicking on menu buttons. 

Many applications run the standard application loop which (1) reads a command, 
(2) does what the command tells it to do, and (3) updates the display to reflect 
what it did. 

Applications generally have their own window, called a frame, and often subdivide 
that window into smaller windows called panes. Common types of panes are menus 
and display panes. 

You can tell CLIM the name of a function that draws the display for a particular 
pane by using the : display-function keyword. CLIM will run that function after 
executing each command. 

In the next chapter you'll see how to make the pieces of the puzzle move when 
you click the mouse directly on them (instead of on menu items). 



Using Presentations in the Fifteen Puzzle 

If you have not already done so, edit the file SYS : CLIM; REL-2; TUTORIAL; PUZZLE- 
2. LISP and run the new version of the application. 

1. Compile the buffer. 

m-X Compile Buffer 

2. At the end of the file there are two or three forms commented out with #| 
and Itf. Evaluate those forms by marking them, wiping them, and yanking 
them into a Listener and pressing END, or by marking them and pressing 

c-sh-E. 



The biggest difference from the previous version is that now you can move pieces 
by clicking on them. Another difference is that the old menu commands Down, 
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Figure 55. The second version of the Fifteen Puzzle lets the user move pieces by 
clicking on them. 



Right, Left and Up are no longer needed; they have been replaced by Exit and Re- 
set. 

This new interface is more pleasant to use. This style of interface, that lets you 
move the piece you want to move by pointing at it, is called a direct manipulation 
interface. In this chapter you will see how CLIM helps you build such an interface 
with a very general and powerful mechanism based on the idea of a presentation. 



The Concept of a Presentation 

When CLIM does output it is doing more than just drawing bits on the screen and 
forgetting about them. CLIM remembers what was drawn on the window. This fea- 
ture is called output recording. Several other features of CLIM make use of output 
recording; one of the most important features enabled by output recording is the 
presentation. 

The purpose of a presentation is to associate some output with an object in the 
program. Any piece of output, whether text or graphics, can form the visual repre- 
sentation of any Lisp object. 

It is important to appreciate the general power that presentations give you, the ap- 
plication writer. In a typical application, the majority of commands are concerned 
with performing some action upon some object. It is part of the power of direct 
manipulation interfaces that they eliminate, for the user, most of the difficulty of 
specifying "what object" to operate upon. By providing a direct link from some- 
thing the user can point at (the output) to the recipient of the desired action (the 
application object), presentations let you implement direct manipulation with great 
ease. 

To make all this specific, consider the Fifteen Puzzle. In the first version of the 
program that we saw in the previous chapter, we had a "Right" command, which 
meant "move the piece that can move right into the space". As you can see by 
running the second version of the program, it is much more preferable to move 
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"that piece there" where the user points at the piece to indicate which piece is to 
be moved. 

If you haven't already done so, you should now look at the source for the new ver- 
sion of the Fifteen Puzzle: SYS:CLIM;REL-2;TUTORIAL;PUZZLE-2.LISP. 

The application frame is the same as the previous version, but immediately follow- 
ing the application definition is a new CLIM form. This is how you create a pre- 
sentation-type: by using the form clim:define-presentation-type. In defining a type 
called puzzle-piece we are expressing our intent to represent a piece of the Fif- 
teen Puzzle by drawing something on the screen. 

(cl im:def ine-presentati on-type puzzle-piece ()) 

Note for the advanced reader: This is a very simple example of 
clim:define-presentation-type. We haven't even explained what makes this a type yet. Many 
more examples will appear later. 

So far we have told CLIM that we want to do output which represents a piece of 
the puzzle. Now we have to do it. Look at the new version of the output routine 
draw-the-display. Notice that the code that writes the characters representing the 
piece is wrapped in clim:with-output-as-presentation. This form means: the fol- 
lowing output (that is, within this extent) represents this object. 

(cl im:with-output-as-presentation (stream position 'puzzle-piece) 
(if (zerop piece) 

(format stream " ") 

(format stream "~2D" piece))) 

Here we are presenting the position, not the piece in that position. 

clim:with-output-as-presentation needs to be given 

• The stream on which you are presenting the object, in this case, the Fifteen 
Puzzle display pane that was passed as an argument to the method; 

• The lisp object you are presenting, in this case the value of position which is a 
lisp object representing the position; 

• The type of presentation you are presenting the object as, in this case, we are 
presenting it as a puzzle-piece. 



Making Commands From Presentations 

Now that we have presentations on the window, we have to use them. 

You have already been introduced to the idea of a command, and to the idea that 
commands may be generated in several different ways, but the only method of en- 
tering a command you have seen so far is by clicking on a menu item. 

In this chapter you see another, very useful, way of making a command — by 
translating a mouse-click on a presentation into a command. Look at the following 
form in the source: 
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(cl im:def ine-presen tat ion-to-command- translator move-a-piece 
(puzzle-piece move f ifteen-puzzle-2) 
(object) 
(multiple-value-bind (yp xp) (floor object 4) 
(list yp xp))) 

The form clim:define-presentation-to-command-translator does exactly what its 
name suggests: it says that "if you click on a presentation of this type, translate 
that into the following command". In the example, a click on anything presented 
as a puzzle-piece translates into a move command. The body of the presentation 
translator returns the argument list for the command. 

The move command is new to this version of the Fifteen Puzzle, but you should 
have no difficulty in understanding what it does. 

(def ine-f ifteen-puzzle-2-command (move) ((yp 'integer) (xp 'integer)) 
...) 

When you compare this command to, say, the Right command of the previous Fif- 
teen Puzzle there are a number of differences you should notice. Most importantly, 
this command takes arguments (which are the X and Y coordinates of the piece to 
move). Notice that the argument list for a command is a little more complicated 
than the argument list to a function. Each element in the argument list is itself a 
list which describes one argument. 

There is no :menu option mentioned in this command, because this is not a com- 
mand we want to put in the menu. 



Exiting an Application 

The second version of the Fifteen Puzzle contains two new menu commands. One 
of them, Reset, simply resets the game board to its original state. You should be 
able to understand the implementation of this command with what you have 
learned already. 

The other command, Exit, provides a way to "cleanly" exit an application, and its 
implementation illustrates some new features of the CLIM substrate. Here is the 
code for the Exit command: 

(def ine-f ifteen-puzzle-2-command (exit :menu t) () 
(cl im: frame-exit cl im:*appl i cation- frame*)) 

Notice a variable that we haven't used before called clim:*application-frame*. As 
part of running the application, CLIM binds this variable to the application object. 
There are many times when this value will be useful to you, and this Exit com- 
mand shows one of them. The application object is passed as an argument to the 
clim:frame-exit function. This function causes the application loop (which we in- 
troduced in the previous chapter) to terminate. 

After an application terminates, the application object is still around in your Lisp 
environment, but no process is running the application's command loop. That 
means you can start up the application again, but unless you do so, you can't give 
it commands. Even when it is not running, an application preserves its internal 
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state, so, for instance, if you restart the Fifteen Puzzle you will find the board in 
the same position that you left it. 



Summary 

A presentation provides an association from output on the window to any Lisp ob- 
ject. clim:define-presentation-type defines a class of presentations. Output done 
within clim:with-output-as-presentation forms the presentation. 

By translating presentations into commands you can provide commands to an appli- 
cation by clicking on pieces of output. clim:define-presentation-to-command- 
translator is used to define how presentations of a particular type translate into a 
command. 

The variable clim:*application-frame* is bound to the application object while 
CLIM runs the application loop. 

Calling the function clim:frame-exit on the application causes the application loop 
to terminate. 

In the next chapter we will fix one of the remaining major problems with the Fif- 
teen Puzzle — that the entire display is redrawn when only a portion of it 
changes. 



Further Development of the Fifteen Puzzle 

In this chapter you will see how to make the Fifteen Puzzle redisplay only those 
pieces of the puzzle that have changed positions. You will also see how to make 
CLIM highlight only those pieces that can actually move. 

The first of these topics is an introduction to a large area of user interface imple- 
mentation which goes under the name incremental redisplay. In general, many ap- 
plications need to change some small part of their display without spending the 
time redrawing those parts of the display that haven't changed. CLIM provides 
several facilities to help you do such redisplay. 

Despite the title of the first section, "Incremental Redisplay the Hard Way", we 
recommend you read this section like any other. The "hard" way is not necessarily 
the "bad" way; in fact the "hard" way may be the best way under certain cir- 
cumstances. 



Incremental Redisplay the Hard Way 

The example for this section is found in SYS: CLIM; REL-2; TUTORIAL; PUZZLE-3. LISP (al- 
so see the section "Code for Puzzle-3 "). As you run this example, notice that the 
display flickers less than previous examples when you move a piece; only those 
pieces that require redisplaying are drawn after each command. As explained in 
the introduction to this chapter, incremental redisplay is a common requirement of 
many applications. 
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Figure 56. The third version of the Fifteen Puzzle uses Incremental Redisplay 

We have already mentioned output recording: CLIM remembers what was written 
to the window. This implies you can't just overwrite old output with new — you 
have to clear pieces of the window. 

As you read the source for this example you should notice several new state vari- 
ables. The most important of these is presentations — a second array the same 
size as the board but instead of holding pieces it holds presentations. Presentations 
are returned from clim:with-output-as-presentation. 

( : panes 

(display : application 

:text-style '(:fix :bold :very-large) 

: di spl ay-f uncti on ' draw-the-di spl ay 

: display-after-commands nil 

: scroll -bars nil 

: initial-cursor-visibil ity nil)) 

Notice that draw-the-display now calls a separate method, draw-piece, to draw 
each individual piece. That's because the move command also calls draw-piece. 
This is a significant difference. The command now explicitly requests the pieces of 
redisplay that it needs. Note the :display-after-commands nil in the application 
frame definition. Because the command requests redisplay, we don't need to ask 
for another complete redisplay. 
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(defmethod draw-piece ((application f ifteen-puzzle-3) 

piece position-y position-x stream) 
(with-slots (char-width line-height presentations) application 
(cl im: stream-set-cursor-position 

stream (* position-x 3 char-width) (* position-y line-height)) 
(when (aref presentations position-y position-x) 
(cl im : erase-output-record 

(aref presentations position-y position-x) stream)) 
(setf (aref presentations position-y position-x) 

(let ((position (+ (* position-y 4) position-x))) 
(write-string " " stream) 

(cl im:with-output-as-presentation (stream position 'puzzle-piece) 
(if (zerop piece) 

(format stream " ") 

(format stream "~2D" piece))))))) 

If you examine draw-piece some more you'll see that not only does it draw the 
piece, storing the presentation in presentations, but it also calls climrerase- 
output-record on the previous presentation. This clears the previous display of the 
piece. 

In the Fifteen Puzzle, we have a simple situation in which none of the presenta- 
tions overlap each other. You should realize that the task would be more compli- 
cated in the general case where presentations might overlap each other. 

This is all rather cumbersome; we will see in the next section how CLIM provides 
a facility to hide most of these details from the programmer. 



Incremental Redisplay the Easy Way 

The example for this section is found in SYS: CLIM; REL-2; TUTORIAL; PUZZLE-4. LISP, 
(also see the section "Code for Puzzle-4"). 
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The fourth version of the Fifteen Puzzle runs exactly like the third version. How- 
ever, when you examine the code, you should see that the code looks a lot simpler 
than the third version. In fact, it looks very much like the second version. Note 
that we don't need a state variable to keep track of the presentations any more. 

(def method draw-the-di splay ((application f if teen-puzzle— 4) stream 

&key &al low-other-keys) 
(with-slots (pieces) application 
(dotimes (y 4) 
(dotimes (x 4) 

(cl im:updating-output (stream :unique-id (+ (* y 4) x) 

:cache-value (aref pieces y x) 
:cache-test #'=) 
(draw-piece application (aref pieces y x) y x stream)))))) 

The extra piece of CLIM functionality that you are seeing for the first time is con- 
tained in the new version of the draw-the-display function; it is named 
climrupdating-output. 

When you run a piece of code using climrupdating-output for the first time it: 

• runs the enclosed code (which presumably produces some output), 

• it associates that output with a tag called its :unique-id, (it is your job as pro- 
grammer to ensure that the :unique-id really is unique in your program) 

• pairs with the :unique-id a value, called a :cache-value. 
When you run the same code again, CLIM: 

• looks up the :unique-id (to find out if it has already run this output before, and 
if so, what :cache-value was supplied last time), 

• examines the :cache-value supplied this time and compares it to the rcache- 
value supplied the last time, 

• and if the two rcache-values do not match, then CLIM must replace the old out- 
put with the new, so it: 

° erases the old output, and 

° runs the enclosed code to produce new output. 

So, in the display function for this version of the Fifteen Puzzle: 
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(def method draw-the-di splay ((application f if teen-puzzle— 4) stream 

&key &al low-other-keys) 
(with-slots (pieces) application 
(dotimes (y 4) 
(dotimes (x 4) 

(cl im:updating-output (stream :unique-id (+ (* y 4) x) 

:cache-value (aref pieces y x) 
:cache-test #'=) 
(draw-piece application (aref pieces y x) y x stream)))))) 

The :unique-id is a number that uniquely represents the position being displayed, 
while the :cache-value is the piece being drawn in that position. The contract of 
climrupdating-output, then, is to redraw that position in the puzzle whenever a 
new piece is found in that position — exactly what is needed to redraw only those 
parts of the puzzle that change. 



Presentation Translator Testers 

The example for this section is found in SYS :CLIM;REL-2; TUTORIAL; PUZZLE-5. LISP. 
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Figure 58. The last version of the Fifteen Puzzle uses a presentation tester so 
that non-movable pieces don't highlight. 



The puzzle is essentially unchanged except that a presentation tester has been 
added to the CLIM presentation-to-command-translator. 

A presentation translator tester is a predicate that verifies or refuses to verify the 
choice of object that CLIM makes. In this way, applications can further control the 
availability of a translator based on information that was not in the presentation. 

It is important to realize that the tester can only "filter out" choices made by 
CLIM's presentation substrate. It cannot make choices available that would not be 
available without the tester. You should also realize that your code has to run ev- 
ery time the mouse moves over a presentation of the type specified in the transla- 
tor. Testers should, therefore, be kept small and fast, or else you can adversely af- 
fect performance in your application. 
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(cl im:def ine-presen tat ion-to-command- translator move-a-piece 
(puzzle-piece move f ifteen-puzzle-5 
: tester ((object) 

(multiple-value-bind (yp xp) (floor object 4) 
(whi ch-way-to-move 
yp xp (fifteen-puzzle-pieces cl im:*appl ication-f rame*))))) 
(object) 
(multiple-value-bind (yp xp) (floor object 4) 
(list yp xp))) 

In the example above, we use the which-way-to-move function, which already re- 
turns nil if the piece cannot move, as the core of the tester. 



Summary 

If your application needs to hold onto presentations explicitly, clim:with-output-as- 
presentation returns the presentation it created. 

If you do not want the CLIM command loop to call its display function after every 
command, give the keyword :display-after-commands the value nil in your appli- 
cation frame definition. 

This just about exhausts the Fifteen Puzzle as a teaching device. Once you have 
learned about graphics in the coming chapters, you might return to the Fifteen 
Puzzle and write another version yourself which displays the puzzle with graphics. 
Or you might implement similar games (the book referenced in "The Fifteen Puz- 
zle — an Elementary Application" has hundreds of them) along similar lines. 



Tic Tac Toe 

This chapter describes the implementation of another small CLIM application — a 
program that plays Tic Tac Toe with the user. As with the Fifteen Puzzle, the 
program is relatively simple, but it illustrates several CLIM features in the con- 
text of a complete working application. 

The code for this application is in SYS: CLIM; REL-2; TUTORIAL; TIC-TAC-TOE. LISP. If 
you have not already done so, edit the file and run the application. 

1. Compile the buffer. 

m-X Compile Buffer 

2. At the end of the file there are two or three forms commented out with #| 
and Itf. Evaluate those forms by marking them, wiping them, and yanking 
them into a Listener and pressing END, or by marking them and pressing 

c-sh-E. 

You can play against the program, with the program taking either player. To start 
a game, click on one of "Play (user X)" or "Play (program X)" in the menu. At this 
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point, empty board positions will be sensitive for your move. When the game ends, 
with either a win or a cat's game, the status window underneath the board will 
display the outcome of the game. 

When a game is not in progress, you may edit the board to set up any arbitrary 
situation. In this state, a click on any board position will cycle through empty, "X" 
and "O". You may start a game from any situation. 



Using a Presentation Type Hierarchy 

In the Fifteen Puzzle of the previous chapters, we only used a single presentation 
type. As you might have guessed, there is much more to presentation types than 
simply naming something to be mouse-sensitive. Presentation types may have sub- 
types and supertypes, forming a hierarchy of types that can be very useful in ex- 
pressing the intent of a program. 

For example, the Tic Tac Toe game lets the user both play the game and edit the 
board at different times. The command that implements "play in this position" is 
only applicable to an empty position on the board, but the command that imple- 
ments "change the mark in this position" is applicable (at the appropriate time) to 
any sort of position. 

The relationship of presentation types to their supertypes is indicated using the 
:inherit-from keyword to clim:define-presentation-type. So the most general type 
is defined: 

(cl im:def ine-presentati on-type board-position ()) 

and then the subtypes are defined as follows: 

(cl im:def ine-presentati on-type empty-board-position () 
: inherit-f rom 'board-position) 

(cl im:def ine-presentati on-type x-board-position () 
: inherit-f rom 'board-position) 

(cl im:def ine-presentati on-type o-board-position () 
: inherit-f rom 'board-position) 

The command com-user-move is the command for playing a move in the game. Its 
argument must be an empty-board-position. 

(def i ne-ti c-tac-toe-command com-user-move 

((pos 'empty-board-position : gesture : select)) 
...) 

The command com-edit-position is the command for editing the board when a 
game is not in progress. Its argument can be any board-position. 

(def i ne-ti c-tac-toe-command com-edit-position 
((pos 'board-position :gesture :select)) 
...) 
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You may have noticed another feature of the argument specifier to the above com- 
mands — there is an extra keyword and value after the name of the argument and 
its presentation-type. This is a convenience feature of CLIM. Saying 

(def i ne-somethi ng-command command-name 

((argument presentation-type : gesture gesture)) 
...) 

is a shorthand way of defining the command and a presentation-to-command- 
translator. It is equivalent to 

(def i ne-somethi ng-command command-name 
((argument presentation-type)) 
...) 

(cl im:def ine-presen tat ion-to-command- translator translator-name 
(empty-board-position command-name something : gesture : select) 
(object) 
(1 ist object)) 



Enabling and Disabling Commands 

An application may wish to temporarily prevent the use of certain commands. This 
can be done by calling setf on climrcommand-enabled to set its value to nil; the 
command may be made available again by changing the value of climrcommand- 
enabled back to t. 

The Tic Tac Toe program enables the commands that are only used for playing 
the game alternately with the commands that are only used for editing the game. 
For example, when the application enters the state where someone is playing the 
game, the following method is called. 

(def method go-to-playing-state ((frame tic-tac-toe)) 

(setf (cl im: command-enabled 'com-play-user-f i rst frame) nil) 
(setf (cl im: command-enabled 'com-play-program-f i rst frame) nil) 
(setf (cl im: command-enabled 'com-edit-position frame) nil) 
(setf (cl im: command-enabled 'com-user-move frame) t)) 

When in this state, the menu items "Play (user X)" and "Play (program X)" are 
not sensitive, nor is the com-edit-position command available via the rselect ges- 
ture. The rselect gesture does translate to the com-user-move command, but only 
from empty positions, of course. 

Command menus containing disabled commands may change their appearance; the 
disabled commands will often be "grayed out" and will not highlight. 

Note for the advanced reader: This behavior, like most of CLIM, can be changed by an applica- 
tion programmer if desired. The default behavior is chosen to provide minimum change in the 
appearance of the menu for minimum distraction of the user. 

Too much use of command disabling can lead to an interface that has many 
"modes", which in general is not a good thing. Use command disabling with re- 
straint. 
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Introduction to Using Graphics Transformations 

A significant feature of CLIM is that it uses transformations as part of performing 
graphical output. Any function that performs graphical output may have its output 
transformed before reaching the output device. 

The Tic Tac Toe application demonstrates one advantage of this facility — the 
writer of a graphical function may write it in simpler coordinates than would oth- 
erwise be possible. If you look at the method display-board in the Tic Tac Toe 
source, you will see that the internal function that draws the "X"s and "0"s of the 
board (draw-element) is written as if it is always going to draw the mark in the 
square bounded by (0,0) and (1,1). Yet the internal routine is used to draw marks 
in all nine positions of the board. 

If you look at where draw-element is called, you will see how this is possible. The 
macros climrwith-translation and climrwith-scaling establish new coordinate sys- 
tems, related to the existing coordinate system by a transformation. (CLIM sup- 
ports a variety of types of transformation, they are documented more fully in the 
reference documentation. See the section "Transformations in CLIM".) 



Summary 

Presentation types form a hierarchy (or more precisely, a lattice). Use the rinherit- 
from keyword inside clim:define-presentation-type to indicate inheritance. 

Graphics transformations let you abstract what you are drawing from where you 
are drawing it. 

Calling setf on climrcommand-enabled can be used to disable and enable an ap- 
plication's commands to allow only appropriate commands to be executable at a 
certain time. 



Plotting Data 

Here we describe a simple application for the plotting of scientific data. The user 
can enter a set of data points, perhaps the results of an experiment. The points 
are plotted on a two dimensional graph. An alternate view allows the examination 
of the data points sorted in a table. Least squares regression can be applied to fit 
a curve to the data and derive an equation which models the process which gener- 
ated the data. 

While studying this application, you will learn about presentation translators, 
pointer gestures, dialogs, transformations, and table formatting. 

To try the application, read the file SYS:CLIM;REL-2;TUT0RIAL;LEAST-SQUARES-1 .LISP 
into an editor buffer. 

1. Compile the buffer. 

m-X Compile Buffer 
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2. At the end of the file there are two or three forms commented out with #| 
and Itf. Evaluate those forms by marking them, wiping them, and yanking 
them into a Listener and pressing END, or by marking them and pressing 

c-sh-E. 

Spend some time playing around with the application. Click the left mouse button 
on the graph, above the X axis (the horizontal line) and to the right of the Y axis 
(the vertical line). A point is plotted where you click the mouse. Plot a few points. 

Now hold the Shift key down and move the mouse over a point. The point is 
highlighted by a small circle drawn around it. In the pointer documentation at the 
bottom of the screen it says something like "Sh-M: Delete Data Point". Click the 
middle mouse button to delete the data point. 

Now hold the Meta key down and move the mouse over another point. The point is 
highlighted as before. Clicking the left mouse button on a point while the Meta key 
is held down will edit that point. A small window will pop up and display the X 
and Y values for the point. Clicking the left mouse button on one of these numbers 
will allow you to change it. Hit the End key when you have finished entering a 
number. If you decide not to change the point then hit Rbort. When you have fin- 
ished editing the coordinates of the point, hit End. 

Once you have entered a few data points, try fitting a curve. Click on [Fit Curve] 
at the bottom of the application's window. A menu will pop up so that you can se- 
lect whether to fit a linear, quadratic or cubic equation to the points you have 
plotted. Click on one with the mouse. It takes a little time for the curve to be cal- 
culated and drawn. 

You can also look at your data arranged in a table. Click on [Switch Display] at 
the bottom of the window. You can now view your data arranged in a table with 
one row per datum. The X coordinate of a point is in the left column and the Y 
coordinate in the right. Note that you can edit and delete points with the mouse 
just as you could from the graphical display. If you have already fit a curve, you 
can see its equation and the correlation coefficient displayed in the pane below the 
one in which the data is tabulated. Try fitting a different curve to your data. 



Input and the Mouse 

Gestures 

The mouse clicks you used to plot, delete and edit data points are called gestures. 
Not all systems have a three button mouse for an input device. Even if they do, 
there might be other user interface considerations which might preclude the use of 
certain mouse button combinations for input to a CLIM application. For this rea- 
son, CLIM adds a layer of abstraction between the actual pointer gesture as per- 
formed by the user and a gesture name representing the pointer gesture. The be- 
havior of the application is defined in terms of gesture names. A system dependent 
mapping is provided between pointer gestures and gesture names. 
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For the Symbolics implementations of CLIM, the gesture name rselect is associated 
with the mouse pointer gesture Left and the gesture named rdelete with 
shift-Middle. The gesture meta-Left is named :edit. 

You should resist the temptation to define gesture names called :left, rmiddle, and 
rright, because this conceptually adds non-portable gestures to your application. 

Accept 

When the application is not busy performing some task, it is waiting for input. 
The kind of input it is waiting for is referred to as the input context. For exam- 
ple, the application might be waiting for a command, for further arguments to a 
command, or for a menu choice, climraccept is the function used to request input 
from the user. 

climraccept prompts the user for input which matches a specified presentation 
type. The user's input is parsed in accordance with the syntax of the printed rep- 
resentation of objects with the given presentation type, climraccept returns what 
the user entered as a lisp object. 

The call to climraccept specifies a presentation type to be used as the input con- 
text. A prompt for the user can also be provided, as well as a default value to be 
offered, climraccept can be used in the traditional mode of alternating requests 
for input from the application followed by input from the user, but today's user ex- 
pects a more sophisticated interface. 

Often, higher level facilities like the command processor or climrmenu-choose will 
invoke climraccept rather than the applications programmer using it directly. The 
programmer will commonly use climraccept within the context of climraccepting- 
values to establish a dialog in which the user can respond to a number of in- 
quiries in whatever order he feels comfortable. 



Editing the Data Set Using Command Translators 

The ability to add points is provided by a presentation translator from climrblank- 
area to the command com-create-data-point. When the application is idle, it is 
waiting for the user to enter a command. When you click the rselect gesture (the 
left mouse button) in a blank part of the plot, that gesture is translated to the 
com-create-data-point. The command takes two real numbers as arguments: the X 
and Y values of the piece of data. 

(def ine-lsq-command com-create-data-point ((x 'real) (y 'real)) 
(add-data-point (make-data-point x y) cl im:*appl ication-f ramex)) 

Anyplace on the screen where there is no currently active presentation matches 
the input context for the presentation type climrblank-area. There is a translator 
that will translate a gesture named rselect on any climrblank-area to this com- 
mand. 
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(cl im:def ine-presen tat ion-to-command- translator new-point 
(cl im: blank-area com-create-data-point lsq 
: gesture : select 
: tester 

((x y window) 
(let ((frame cl im:*appl ication-f rame*)) 

(with-slots (data-left-margin data-top-margin 

data-right-margin data-bottom-margin) frame 
(and (eql window (cl im: get-frame-pane frame 'display)) 
(<= data-left-margin x data-right-margin) 
(<= data-top-margin y data-bottom-margin)))))) 

(x y) 

(with-slots (data-transform) cl im:*appl ication-f rame* 
(multiple-value-bind (x y) 

(cl im:untransform-position data-transform x y) 
(list x y)))) 

The value of the rtester keyword argument specifies the argument list and body of 
a function to be used to constrain the applicability of the translator. We don't 
want the user to be able to invoke the com-create-data-point command for just 
any blank area, only for blank area in the display pane which is within the con- 
fines of our graph's axes. 

Note that the X and Y arguments to the command refer to coordinates in data- 
space. The translator receives its arguments in window coordinates, and trans- 
forms them to data coordinates so that they will be suitable as arguments to the 
command. This relationship between our data points and the points on the screen 
is discussed below. 

The commands for deleting and editing data points are also provided through the 
use of command translators. There is a translator to the command com-delete- 
data-point which is invoked via the rdelete gesture on a point which has been 
plotted. 

(def i ne-1 sq-command corn-del ete-data-poi nt 
((point 'data-point :gesture :delete)) 
(del ete-data-poi nt point cl im:*appl ication-f rame*)) 

There is a similar translator from data points via the :edit gesture to the com- 
mand com-edit-data-point. This command is described below in the section about 
dialogs. 



Fitting a Curve: Menus 

When you click on [Fit Curve], the application asks you what kind of curve you 
would like to fit. It does this through a pop-up menu. Menus can be used to ask 
the user to select from a number of choices. 
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(cl im: menu-choose xknown-curvesx 
:label "Curve to Fit" 
:printer #' (lambda (curve stream) 

(write-string (curve-name curve) stream))) 

The contract of climrmenu-choose is to allow the user to select one choice from a 
list of choices. The list of Lisp objects representing the choices is the only manda- 
tory argument to climrmenu-choose. In the example above, the user is asked to 
select one curve from the list *known-curves*. 

The appearance of items in the menu is controlled by the optional rprinter argu- 
ment. If you don't supply one, climrmenu-choose will use a default printer for 
Lisp objects. If you supply one, it must be a function of two arguments — the ob- 
ject to be printed and the stream. In the example above, we supply a printer that 
prints the names of curve objects. We could have also supplied a printer that drew 
an icon representing the type of curve; this is left as an exercise for the interested 
reader. 

The optional rlabel argument to climrmenu-choose allows the programmer to sup- 
ply a descriptive label on the pop-up menu. Such a label helps add context to the 
user interaction. 



Groups of Related Questionsr Dialogs 

Sometimes an application must ask the user several related questions. This is done 
through the use of dialogs. The application programmer describes a dialog in the 
body of an invocation of climraccepting-values. The command for altering the co- 
ordinates of a data point provides us with an example of a dialog. 

(def i ne-1 sq-command com-edi t-data-poi nt 
((point 'data-point :gesture :edit)) 
(let ((x (point-x point)) 
(y (point-y point)) 
(stream xstandard-outputx)) 
(cl im: accepting- values 
(stream 

:own-window '(: right-margin (20 :character)) 
:label "New coordinates for the point") 
(fresh-line stream) 
(setq x (dim: accept 'real 

: stream stream 
prompt "X: " 
default x)) 
(fresh-line stream) 
(setq y (clim: accept 'real 

: stream stream 
: prompt "Y: " 
: default y))) 
(al ter-data-point point cl im:*appl ication-f ramex x y))) 
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Within the dynamic context of climraccepting-values, climraccept is used to pose 
each individual query. The usual CLIM output facilities (tables, indented output, 
and so forth) could be used to describe the appearance of the dialog. In this exam- 
ple fresh-line is used so that each request for input will appear on its own line. 

Within climraccepting-values, the user can answer the queries in any order, by 
selecting with the mouse. Because he needn't answer all of the queries, calls to 
climraccept from within climraccepting-values must use rdefault to specify a de- 
fault value to be returned by that call to climraccept. 

The [Set Axis Ranges] menu item implemented by the com-set-axis-ranges com- 
mand is another example of the use of climraccepting-values and climraccept to 
construct a dialog. In addition, it uses climraccept-values-command-button to cre- 
ate a button, appearing as the line of text "Set ranges to encompass all points", 
which, when clicked on, changes the minimum and maximum values for the X and 
Y axis ranges, such that the X axis extends from the point with the smallest X co- 
ordinate to the point with the largest X coordinate and the Y axis extends from 
the smallest Y coordinate to the largest Y coordinate. 
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(def ine-lsq-command (com-set-axis-ranges :menu t) 


(let ((frame cl im:*appl i cation-frame*) 
(stream xstandard-outputx)) 
(with-slots (data-x-min data-x-max data-y-min data-y-max 

data-points data-transform data-points-tick) frame 
(incf data-points-tick) 
(let ((min-x data-x-min) 
(max-x data-x-max) 
(min-y data-y-min) 
(max-y data-y-max)) 
(cl im: accepting- values 
(stream 

:own-window '(: right-margin (20 :character)) 
:label "Enter the ranges for the coordinate axes") 
(format stream "~&Range of X axis: ") 
(flet ((get-one (value id) 
(dim: accept 'real 

: stream stream 
: default value 
:query-identif ier id 
: prompt nil))) 
(setq min-x (get-one min-x 'x-min)) 
(format stream " to ") 
(setq max-x (get-one max-x 'x-max)) 
(format stream "~&Range of Y axis: ") 
(setq min-y (get-one min-y 'y-min)) 
(format stream " to ") 
(setq max-y (get-one max-y 'y-max))) 
(fresh-line stream) 
(terpri stream) 
(cl im : accept-val ues-command-button 

(stream :query-identif ier 'al 1-of-them) 

"Set ranges to encompass all points" 
(mul tiple-value-setq (min-x min-y max-x max-y) 
(data-range frame))) 
(fresh-line stream) 
(terpri stream)) 
(setq data-x-min min-x 
data-x-max max-x 
data-y-min min-y 
data-y-max max-y)) 
(determi ne-data-transf orm frame) ) ) ) 

Also note the use of the : query-identifier keyword in the calls to climraccept. 
Within climraccepting-values, every call to climraccept must have a unique query 
identifier associated with it. Under most circumstances, the value provided for the 
rprompt keyword argument would be sufficient for use as the : query-identifier as 
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well. In fact, if no : query-identifier is specified, CLIM will default to using the 
prompt as the query identifier. 



Points, Transforms and Coordinate Spaces 

Our application actually works with two coordinate spaces: 

• an abstract coordinate space appropriate for the data being entered and manipu- 
lated 

• the coordinate space of the display pane in which the points are plotted. 

These two coordinate systems are related by a transform which maps from points 
in the abstract coordinate space of the data to the coordinate space of the display 
pane. 

By establishing the transform as part of the drawing environment when we plot 
the points, we can plot the points using their abstract coordinates and have them 
drawn at the location corresponding to their display pane coordinates. 



A Tabular Display of the Data 

Layouts 

Our user might want to examine his data in tabular form. We've added another 
pane to the application which displays the data in a table. Though the tabular dis- 
play could be placed next to the plot, the user would probably want as much 
screen real estate as possible devoted to his graph. We can put the tabular display 
in a separate layout. CLIM applications can have their panes arranged in different 
layouts. A layout describes an arrangement of some (or all) of the application's 
panes. You have already seen one layout, named drawing-layout, with the com- 
mand menu and the display pane. We can add a second layout containing the 
same command menu pane and a pane for the tabular display. 
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(cl im:def ine-appl ication-f rame lsq () 
(...) 
(: command-table (lsq : inherit-f rom (cl im:accept-values-pane))) 
( : panes 

(display : application 

: di spl ay-f uncti on ' draw-data-di spl ay 
: incremental-redisplay t 
: display-after-commands t 
: scroll -bars nil) 
(table : application 

: incremental-redisplay t 
:scroll-bars :vertical 
: di spl ay-f uncti on ' tabul ate-data-poi nts) 
(equation : application 

: display- function 'print-equation-of -curve 
: display-after-commands t 
: incremental-redisplay t 
: scroll -bars nil)) 
( : layouts 

(drawing-layout 

(cl im: vertical ly () display)) 
(tabular-layout 

(clim:vertically () (7/8 table) (1/8 equation))))) 



Our pane for the tabular display is named table. It is visible in the layout named 
tabular-layout. The table of data is drawn by the pane's display function, 
tabulate-data-points, which is described below. 

Our user will need a way to switch between the two layouts. We can define the 
[Switch Display] command in the command menu. It figures out what the currently 
displayed layout is by calling climrframe-current-layout and then sets the cur- 
rent layout to the other layout by calling setf on climrframe-current-layout. 

(def ine-lsq-command (switch-configurations :menu "Switch Display") () 
(let ((frame cl im:*appl ication-f rame*)) 
(let ((new-config 

(case (cl im: frame-current-layout frame) 
(drawing-layout 
(setf (cl im: command-enabled 
(setf (cl im: command-enabled 
'tabular-layout) 
(tabular-layout 
(setf (cl im: command-enabled 
(setf (cl im: command-enabled 
' drawi ng-1 ay out) ) ) ) 
(setf (cl im: frame-current-layout frame) new-config)))) 



com-zoom-in frame) nil) 
com-zoom-out frame) nil) 



com-zoom-in frame) t) 
com-zoom-out frame) t) 
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The Table 

The table pane displays the data in tabular form. The table has two columns: one 
for X coordinates and one for Y coordinates. The table has a row at the top for 
column headings (in italics). Each succeeding row represents a datum, with the 
datum's X and Y coordinates displayed in cells which fall under their respective 
columns. 

The function tabulate-data-points displays this table of data. It is invoked when 
CLIM draws the contents of the table pane, tabulate-data-points uses the macros 
clim:formatting-table, clim:formatting-row and clim:formatting-cell to describe 
the contents of the table. The clim:formatting-table form describes the contents 
of a single table. 

Within it, clim:formatting-row is used to describe each row of the table. The rows 
appear in the table in the same order in which their corresponding 
clim:formatting-row forms are evaluated. In our table of data, there is a row for 
column headings followed by one row for each point in the data set. 

Within each row, clim:formatting-cell is used to describe the contents of each cell 
of that row. Each row of our table has one cell for the X coordinate of the data 
point and one cell for the Y coordinate. The clim:formatting-cell forms are evalu- 
ated in the order such that the cell will fall into the appropriate column. 

We want each row of our table to remember what data point it displays. 
clim:with-output-as-presentation is used to associate the row with the datum it 
displays. This allows each row to be sensitive as a data-point. One benefit of this 
is that the rdelete gesture will invoke the com-delete-data-point command for da- 
ta points displayed as a row in the tabular view as well as for points displayed as 
dots in the plot view. In the invocation of clim:with-output-as-presentation, we 
specify :single-box t to emphasize that what is important is the datum, the entire 
row, rather than the individual cells containing the coordinates. 
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(def method tabulate-data-points ((frame lsq) pane) 
(f resh-1 ine pane) 
(flet ((do-point (point stream) 

(cl im:with-output-as-presentation 

(stream point 'data-point :single-box t) 
(cl im: formatting-row (stream) 
(cl im: formatting-cel 1 (stream) 

(format stream "~F" (point-x point))) 
(cl im: formatting-cel 1 (stream) 

(format stream "~F" (point-y point))))))) 
(cl im: formatting-table (pane) 
;; print column headings 
(cl im: formatting-row (pane) 

(cl im:with-text-face (pane : italic) 

(cl im: formatting-cel 1 (pane :min-width 20 

:align-x :center) 
(write-string "X" pane)) 
(cl im: formatting-cel 1 (pane :min-width 20 

:align-x :center) 
(write-string "Y" pane)))) 
(with-slots (data-points) frame 
(dolist (point data-points) 
(do-point point pane)))))) 



Summary 

CLIM's primary facility for requesting input from the user is climraccept. It 
prompts the use and establishes an input context to help the user enter appropri- 
ate responses. 

CLIM provides gesture names as a layer of abstraction between applications and 
pointer input devices. 

A command can be invoked on an application object via a presentation translator 
from a presentation of the object, independent of the appearance of the object pre- 
sented. The rdelete gesture on a data point deletes the point whether it appears as 
a dot in the plotting pane or as a line of text in the table pane. 

The presentation type clim:blank-area matches parts of the display where nothing 
is displayed. A translator from clim:blank-area to the com-create-data-point com- 
mand was used to allow the entry of new data points by clicking on the plotting 
pane. 

The application can prompt the use for input from a menu by calling climrmenu- 
choose. This was used to allow the user to select which type of function to fit the 
data to. 

More complicated queries to the user take the form of accepting values dialogs. 
Within the context of climraccepting-values, climraccept and any output format- 
ting facilities can be used to describe a set of related queries for the user to re- 
spond to. 
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Inside a dialog, a command button can be used to invoke a command. In the op- 
tions dialog pane, a button was provided to widen the scope of the plotting pane to 
encompass all the data points. 

Transformations can be used to map between the abstract coordinate space of an 
application and the coordinate space of the display. 

The rlayouts option to clim:define-application-frame can be used to describe the 
arrangement of your applications panes. These arrangements are called layouts. An 
application can have several such layouts. A pane can appear in more than one 
layout. You select which layout is the active one using setf on climrframe-current- 
layout. 

Output can be displayed in tabular form using clim:formatting-table, 
clim:formatting-row and clim:formatting-cell. The table facility arranges the out- 
put into regular rows and columns. clim:with-output-as-presentation can be used 
in conjunction with the table facility (or anyplace else) to make table rows mouse 
sensitive. 



Appendices 

Code for Puzzle-1 

This code can be found in the file SYS:CLIM;REL-2;TUT0RIAL;PUZZLE-1 .LISP. 

;;; -*- Mode: Lisp; Syntax: ANSI-Common-Lisp; Package: CLIM-USER; Base: 10 -*- 

(def ine-appl i cation-frame f ifteen-puzzle-1 () 

((pieces :initform (make-array '(4 4) : initial-contents '((1 2 3 4) 

(5 6 7 8) 
(9 10 11 12) 
(13 14 15 0))))) 
(:menu-bar nil) 
( : panes 

(display application 

:text-style '(:fix :bold :very-large) 
: di spl ay-f uncti on ' draw-the-di spl ay 
: scroll -bars nil) 
(menu : command-menu)) 
( : layouts 
(main 

(vertically () display menu)))) 

;;; this draws the entire display 
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(def method draw-the-di splay ((application f ifteen-puzzle-1) stream 

&key &al low-other-keys) 
(with-slots (pieces) application 
(dotimes (y 4) 
(dotimes (x 4) 

(let ((piece (aref pieces y x))) 
(if (zerop piece) 

(format stream " ") 
(format stream "~2D " piece)))) 
(terpri stream)))) 

;;; useful macrology - the body will be run with x and y bound to 
;;; the coordinates of the empty cell 

(def macro f ind-empty-piece-and-do ((y x) &body body) 
'(block find-empty-piece 
(dotimes (,y 4) 
(dotimes (,x 4) 

(when (zerop (aref pieces ,y ,x)) 
,@body 
(return- from f i nd-empty-pi ece) ) ) ) ) ) 

(def ine-f ifteen-puzzle-1 -command (down :menu t) () 
(with-slots (pieces) *appl i cation-frame* 
(f ind-empty-piece-and-do (y x) 
(if (not (zerop y)) 

(rotatef (aref pieces y x) (aref pieces (- y 1) x)))))) 

(def ine-f ifteen-puzzle-1 -command (up :menu t) () 
(with-slots (pieces) *appl i cation-frame* 
(f ind-empty-piece-and-do (y x) 
(if (not (= y 3)) 

(rotatef (aref pieces y x) (aref pieces (+ y 1) x)))))) 

(def ine-f ifteen-puzzle-1 -command (left :menu t) () 
(with-slots (pieces) *appl i cation-frame* 
(f ind-empty-piece-and-do (y x) 
(if (not (= x 3)) 

(rotatef (aref pieces y x) (aref pieces y (+ x 1))))))) 

(def ine-f ifteen-puzzle-1 -command (right :menu t) () 
(with-slots (pieces) *appl i cation-frame* 
(f ind-empty-piece-and-do (y x) 
(if (not (zerop x)) 

(rotatef (aref pieces y x) (aref pieces y (- x 1))))))) 
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n\\ 



(setq fp1 (make-application-frame 'f ifteen-puzzle-1 

:left 200 :right 400 :top 150 :bottom 350)) 
(run-frame-top-level fp1) 
lift 



Code for Puzzle-2 

This code can be found in the file SYS :CLIM;REL-2; TUTORIAL; PUZZLE-2. LISP. 

;;; -x- Mode: Lisp; Syntax: ANSI-Common-Lisp; Package: CLIM-USER; Base: 10 -x- 

(def ine-appl i cation-frame f ifteen-puzzle-2 () 

((pieces :initform (make-array '(4 4) : initial-contents '((1 2 3 4) 

(5 6 7 8) 
(9 10 11 12) 
(13 14 15 0))))) 
( : panes 

(display : application 

:text-style '(:fix :bold :very-large) 
: di spl ay-f uncti on ' draw-the-di spl ay 
: scroll -bars nil 

: initial-cursor-visibil ity nil)) 
( : layouts 
(main 

(vertically () display)))) 

(def ine-presentati on-type puzzle-piece ()) 

(def method draw-the-di spl ay ((application f ifteen-puzzle-2) stream 

&key &al low-other-keys) 
(with-slots (pieces) application 
(dotimes (y 4) 
(dotimes (x 4) 

(let ((piece (aref pieces y x)) 
(position (+ (x y 4) x))) 
(write-string " " stream) 

(with-output-as-presentation (stream position 'puzzle-piece) 
(if (zerop piece) 

(format stream " ") 
(format stream "~2D" piece))))) 
(terpri stream)))) 
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if the piece at (xp,yp) can be moved, five values are returned: 

- the coordinates of the space in the puzzle, 

- delta-y and delta-x representing the direction on the puzzle from 
space towards the piece at (xp,yp) 

- and the number of pieces to move 
if the piece at (xp,yp) cannot be moved, nil is returned 

(defun which-way-to-move (yp xp pieces) 

(macrolet ((is-space (y x) ' (zerop (aref pieces ,y ,x)))) 
(loop for x from (+ xp 1) to 3 do 
(when (is-space yp x) 

(return-from which-way-to-move (values yp x -1 (- x xp))))) 
(loop for x from (- xp 1) downto do 
(when (is-space yp x) 

(return-from which-way-to-move (values yp x 1 (- xp x))))) 
(loop for y from (+ yp 1) to 3 do 
(when (is-space y xp) 

(return-from which-way-to-move (values y xp -1 (- y yp))))) 
(loop for y from (- yp 1) downto do 
(when (is-space y xp) 

(return-from which-way-to-move (values y xp 1 (- yp y))))))) 

(def ine-f ifteen-puzzle-2-command (move) ((yp 'integer) (xp 'integer)) 
(with-slots (pieces) xappl i cation-frame* 

(multiple-value-bind (start-y start-x dy dx n-moves) 
(which-way-to-move yp xp pieces) 
(when dx 

(loop repeat n-moves 

for x1 = start-x then x2 

for x2 = (+ x1 dx) then (+ x2 dx) 

for y1 = start-y then y2 

for y2 = (+ y1 dy) then (+ y2 dy) 

do (setf (aref pieces y1 x1) (aref pieces y2 x2)) 

finally (setf (aref pieces yp xp) 0)))))) 

(def i ne-presentati on-to-command-transl ator move-a-pi ece 
(puzzle-piece move f ifteen-puzzle-2) 
(object) 
(multiple-value-bind (yp xp) (floor object 4) 
(list yp xp))) 
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(def ine-f ifteen-puzzle-2-command (reset :menu t) () 
(with-slots (pieces) xappl i cation-frame* 
(loop for y from to 3 do 

(loop with 4y+1 = (+ (* 4 y) 1) 
for x from to 3 do 
(setf (aref pieces y x) (mod (+ 4y+1 x) 16)))))) 

(def ine-f ifteen-puzzle-2-command (exit :menu t) () 
(frame-exit *appl i cation- frame*)) 

tfll 



(setq fp2 (make-application-frame 'f ifteen-puzzle-2 

:left 400 :right 600 :top 150 :bottom 350)) 
(run-frame-top-level fp2) 
lift 



Code for Puzzle-3 

This code can be found in the file SYS :CLIM;REL-2; TUTORIAL; PUZZLE-3. LISP. 

;;; -*- Mode: Lisp; Syntax: ANSI-Common-Lisp; Package: CLIM-USER; Base: 10 

;;; things to fix - replace encoded position 

;;; - auto-size window , get line-height, char-width 



(def ine-appl ication-f rame f ifteen-puzzle-3 () 

((pieces :initform (make-array '(4 4) : initial-contents '((1 2 3 4) 

(5 6 7 8) 



(presentations :initform (make-array '(4 4))) 
(char-width :initform 12) 
(line-height :initform 30)) 
( : panes 

(display application 

:text-style '(:fix :bold :very-large) 
: di spl ay-f uncti on ' draw-the-di spl ay 
: display-after-commands nil 
: scroll -bars nil 

: initial-cursor-visibil ity nil)) 
( : layouts 
(main 

(vertically () display)))) 



(9 10 11 12) 
(13 14 15 0)))) 
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(def ine-presentati on-type puzzle-piece ()) 

(defmethod draw-piece ((application f ifteen-puzzle-3) 

piece position-y position-x stream) 
(with-slots (char-width line-height presentations) application 
(stream-set-cursor-position stream (* position-x 3 char-width) 

(* position-y line-height)) 
(when (aref presentations position-y position-x) 

(erase-output-record (aref presentations position-y position-x) stream)) 
(setf (aref presentations position-y position-x) 

(let ((position (+ (* position-y 4) position-x))) 
(write-string " " stream) 

(with-output-as-presentation (stream position 'puzzle-piece) 
(if (zerop piece) 

(format stream " ") 

(format stream "~2D" piece))))))) 

(defmethod draw-the-di splay ((application f ifteen-puzzle-3) stream 

&key &al low-other-keys) 
(with-slots (pieces) application 
(dotimes (y 4) 
(dotimes (x 4) 

(draw-piece application (aref pieces y x) y x stream))))) 

(defun which-way-to-move (yp xp pieces) 

(macrolet ((is-space (y x) '(zerop (aref pieces ,y ,x)))) 
(loop for x from (+ xp 1) to 3 do 
(when (is-space yp x) 

(return-from which-way-to-move (values yp x -1 (- x xp))))) 
(loop for x from (- xp 1) downto do 
(when (is-space yp x) 

(return-from which-way-to-move (values yp x 1 (- xp x))))) 
(loop for y from (+ yp 1) to 3 do 
(when (is-space y xp) 

(return-from which-way-to-move (values y xp -1 (- y yp))))) 
(loop for y from (- yp 1) downto do 
(when (is-space y xp) 

(return-from which-way-to-move (values y xp 1 (- yp y))))))) 
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(def ine-f ifteen-puzzle-3-command (move) ((yp 'integer) (xp 'integer)) 
(with-slots (pieces) xappl i cation-frame* 

(let ((display-pane (get-frame-pane *appl i cation-frame* 'display))) 
(flet ((update (y x new-piece) 

(setf (aref pieces y x) new-piece) 

(draw-piece *appl i cation-frame* new-piece y x display-pane))) 
(multiple-value-bind (start-y start-x dy dx n-moves) 
(which-way-to-move yp xp pieces) 
(when dx 

(loop repeat n-moves 

for x1 = start-x then x2 

for x2 = (+ x1 dx) then (+ x2 dx) 

for y1 = start-y then y2 

for y2 = (+ y1 dy) then (+ y2 dy) 

do (update y1 x1 (aref pieces y2 x2)) 

finally (update yp xp 0)))))))) 

(def i ne-presentati on-to-command-transl ator move-a-pi ece 
(puzzle-piece move f ifteen-puzzle-3) 
(object) 
(multiple-value-bind (yp xp) (floor object 4) 
(list yp xp))) 

(def ine-f ifteen-puzzle-3-command (reset :menu t) () 
(with-slots (pieces presentations) *appl i cation-frame* 
(loop for y from to 3 do 

(loop with 4y+1 = (+ (* 4 y) 1) 
for x from to 3 do 
(setf (aref pieces y x) (mod (+ 4y+1 x) 16)))) 
(let ((display-pane (get-frame-pane *appl i cation-frame* 'display))) 
(window-clear display-pane) 
(dotimes (y 4) 
(dotimes (x 4) 

(setf (aref presentations y x) nil))) 
(draw-the-di splay *appl i cation-frame* display-pane)))) 

(def ine-f ifteen-puzzle-3-command (exit :menu t) () 
(frame-exit *appl i cation- frame*)) 

tfll 



(setq fp3 (make-application-frame 'f ifteen-puzzle-3 

:left 400 :right 600 :top 150 :bottom 350)) 
(run-frame-top-level fp3) 

lift 
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Code for Puzzle-4 

This code can be found in the file SYS :CLIM;REL-2; TUTORIAL; PUZZLE-4. LISP. 

;;; -*- Mode: Lisp; Syntax: ANSI-Common-Lisp; Package: CLIM-USER; Base: 10 -x- 

(def ine-appl i cation-frame f ifteen-puzzle-4 () 

((pieces :initform (make-array '(4 4) : initial-contents '((1 2 3 4) 

(5 6 7 8) 
(9 10 11 12) 
(13 14 15 0)))) 
(char-width :initform 12) 
(line-height :initform 30)) 
( : panes 

(display application 

: default-text-style '(:fix :bold :very-large) 
: di spl ay-f uncti on ' draw-the-di spl ay 
: incremental-redisplay t 
: scroll -bars nil 

: initial-cursor-visibil ity nil)) 
( : layouts 
(main 

(vertically () display)))) 



(def ine-presentati on-type puzzle-piece ()) 

(defmethod draw-piece ((application f ifteen-puzzle-4) 

piece position-y position-x stream) 
(with-slots (char-width line-height) application 

(stream-set-cursor-position stream (* position-x 3 char-width) 

(* position-y line-height))) 
(let ((position (+ (* position-y 4) position-x))) 
(write-string " " stream) 

(with-output-as-presentation (stream position 'puzzle-piece) 
(if (zerop piece) 

(format stream " ") 

(format stream "~2D" piece))))) 

(defmethod draw-the-di spl ay ((application f ifteen-puzzle-4) stream 

&key &al low-other-keys) 
(with-slots (pieces) application 
(dotimes (y 4) 
(dotimes (x 4) 

(updating-output (stream :unique-id (+ (* y 4) x) 

:cache-value (aref pieces y x) 
:cache-test #'=) 
(draw-piece application (aref pieces y x) y x stream)))))) 
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(defun which-way-to-move (yp xp pieces) 

(macrolet ((is-space (y x) ' (zerop (aref pieces ,y ,x)))) 
(loop for x from (+ xp 1) to 3 do 
(when (is-space yp x) 

(return-f rom which-way-to-move (values yp x -1 (- x xp))))) 
(loop for x from (- xp 1) downto do 
(when (is-space yp x) 

(return-f rom which-way-to-move (values yp x 1 (- xp x))))) 
(loop for y from (+ yp 1) to 3 do 
(when (is-space y xp) 

(return-f rom which-way-to-move (values y xp -1 (- y yp))))) 
(loop for y from (- yp 1) downto do 
(when (is-space y xp) 

(return-from which-way-to-move (values y xp 1 (- yp y))))))) 

(def ine-f ifteen-puzzle— 4-command (move) ((yp 'integer) (xp 'integer)) 
(with-slots (pieces) *appl i cation-frame* 

(multiple-value-bind (start-y start-x dy dx n-moves) 
(which-way-to-move yp xp pieces) 
(when dx 

(loop repeat n-moves 

for x1 = start-x then x2 

for x2 = (+ x1 dx) then (+ x2 dx) 

for y1 = start-y then y2 

for y2 = (+ y1 dy) then (+ y2 dy) 

do (setf (aref pieces y1 x1) (aref pieces y2 x2)) 

finally (setf (aref pieces yp xp) 0)))))) 

(def i ne-presentati on-to-command-transl ator move-a-pi ece 
(puzzle-piece move f ifteen-puzzle— 4) 
(object) 
(multiple-value-bind (yp xp) (floor object 4) 
1 (,yp ,xp))) 

(def ine-f ifteen-puzzle— 4-command (reset :menu t) () 
(with-slots (pieces) *appl i cation-frame* 
(loop for y from to 3 do 

(loop with 4y+1 = (+ (* 4 y) 1) 
for x from to 3 do 
(setf (aref pieces y x) (mod (+ 4y+1 x) 16)))))) 

(def ine-f ifteen-puzzle-4-command (exit :menu t) () 
(frame-exit *appl i cation- frame*)) 
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n\\ 



(setq fp4 (make-application-frame 'f ifteen-puzzle-4 

:left 600 :right 800 :top 150 :bottom 350)) 
(run-f rame-top-level fp4) 
lift 



Code for Puzzle-5 

This code can be found in the file SYS :CLIM;REL-2; TUTORIAL; PUZZLE-5. LISP. 

;;; -x- Mode: Lisp; Syntax: ANSI-Common-Lisp; Package: CLIM-USER; Base: 10 -x- 

(def ine-appl i cation-frame f ifteen-puzzle-5 () 

((pieces :initform (make-array '(4 4) : initial-contents '((1 2 3 4) 

(5 6 7 8) 
(9 10 11 12) 
(13 14 15 0))) 
: reader fifteen-puzzle-pieces) 
(char-width :initform 12) 
(line-height :initform 30)) 
( : panes 

(display : application 

: default-text-style '(:fix :bold :very-large) 
: di spl ay-f uncti on ' draw-the-di spl ay 
: incremental-redisplay t 
: scroll -bars nil 

: initial-cursor-visibil ity nil)) 
( : layouts 
(main 

(vertically () display)))) 



(def ine-presentati on-type puzzle-piece ()) 

(defmethod draw-piece ((application f ifteen-puzzle-5) 

piece position-y position-x stream) 
(with-slots (char-width line-height) application 

(stream-set-cursor-position stream (x position-x 3 char-width) 

(x position-y line-height))) 
(let ((position (+ (x position-y 4) position-x))) 
(write-string " " stream) 

(with-output-as-presentation (stream position 'puzzle-piece) 
(if (zerop piece) 

(format stream " ") 

(format stream "~2D" piece))))) 
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(def method draw-the-di splay ((application f ifteen-puzzle-5) stream 

&key &al low-other-keys) 
(with-slots (pieces) application 
(dotimes (y 4) 
(dotimes (x 4) 

(updating-output (stream :unique-id (+ (* y 4) x) 

:cache-value (aref pieces y x) 
:cache-test #'=) 
(draw-piece application (aref pieces y x) y x stream)))))) 



(defun which-way-to-move (yp xp pieces) 

(macrolet ((is-space (y x) ' (zerop (aref pieces ,y ,x)))) 
(loop for x from (+ xp 1) to 3 do 
(when (is-space yp x) 

(return-from which-way-to-move (values yp x -1 (- x xp))))) 
(loop for x from (- xp 1) downto do 
(when (is-space yp x) 

(return-from which-way-to-move (values yp x 1 (- xp x))))) 
(loop for y from (+ yp 1) to 3 do 
(when (is-space y xp) 

(return-from which-way-to-move (values y xp -1 (- y yp))))) 
(loop for y from (- yp 1) downto do 
(when (is-space y xp) 

(return-from which-way-to-move (values y xp 1 (- yp y))))))) 



) ((yp 'integer) (xp 'integer)) 



(def ine-f ifteen-puzzle-5-command (move) ((; 
(with-slots (pieces) xappl i cation-frame* 

(multiple-value-bind (start-y start-x dy dx n-moves) 
^hich-way-to-move yp xp pieces) 



(wr 



(when dx 

(loop repeat n-moves 

for x1 = start-x then x2 

for x2 = (+ x1 dx) then (+ x2 dx) 

for y1 = start-y then y2 

for y2 = (+ y1 dy) then (+ y2 dy) 

do (setf (aref pieces y1 x1) (aref pieces y2 x2)) 

finally (setf (aref pieces yp xp) 0)))))) 
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(def i ne-presentati on-to-command-transl ator move-a-pi ece 
(puzzle-piece move f ifteen-puzzle-5 
: tester ((object) 

(multiple-value-bind (yp xp) (floor object 4) 
(whi ch-way-to-move 
yp xp (fifteen-puzzle-pieces *appl i cation-frame*))))) 
(object) 
(multiple-value-bind (yp xp) (floor object 4) 
(list yp xp))) 

(def ine-f ifteen-puzzle-5-command (reset :menu t) () 
(with-slots (pieces) *appl i cation-frame* 
(loop for y from to 3 do 

(loop with 4y+1 = (+ (* 4 y) 1) 
for x from to 3 do 
(setf (aref pieces y x) (mod (+ 4y+1 x) 16)))))) 

(def ine-f ifteen-puzzle-5-command (exit :menu t) () 
(frame-exit *appl i cation- frame*)) 

tfll 



(setq fp5 (make-application-frame 'f ifteen-puzzle-5 

:left 600 :right 800 :top 150 :bottom 350)) 
(run-frame-top-level fp5) 

lift 



Code for Tic Tac Toe 

This code can be found in the file SYS :CLIM;REL-2; TUTORIAL; TIC-TAC-TOE. LISP. 

;;; -*- Mode: Lisp; Syntax: ANSI-Common-Lisp; Package: CLIM-USER; Base: 10 -*- 

(def constant *X* 1) 
(def constant *0* -1) 
(defconstant *empty* 0) 

(def i ne-presentati on-type board-position ()) 

(def i ne-presentati on-type empty-board-position () 
: inherit-f rom 'board-position) 

(def i ne-presentati on-type x-board-position () 
: inherit-f rom 'board-position) 
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(def ine-presentati on-type o-board-position () 
: inherit-f rom 'board-position) 



(cl im:def ine-appl i cat ion- frame tic-tac-toe 



(3 3) : initial -element *empty*)) 




((board :initform (make-array 
(board-diagnosis :initform t) 
(whose-move :initform xXx) 
(user-plays :initform *X*)) 
( : panes 

(board-display : application 

: display-function 'display-board 
: incremental-redisplay t 
: scroll -bars nil) 
(status : application 

: di spl ay-f uncti on ' di spl ay-status 
: incremental-redisplay t 
: scroll -bars nil)) 
( : layouts 
(main 

(vertically () 

(9/10 board-display) 
(1/10 status))))) 



(defmethod clos: initial ize-instance :after ((frame tic-tac-toe) &rest args) 
(declare (ignore args)) 
(go-to-stopped-state frame)) 

(def ine-tic-tac-toe-command (com-tic-tac-toe-exit :menu "Exit") () 
(cl im: frame-exit xappl i cation- frame*)) 



(def ine-tic-tac-toe-command (com-reset-tic-tac-toe :menu 
(reset-board *appl i cation-frame*) 
(go-to-stopped-state *appl i cati on-frame*) ) 



'Reset") () 



(defmethod reset-board ((frame tic-tac-toe)) 

(window-clear (get-frame-pane frame 'board-display)) 
(with-slots (board board-diagnosis) frame 
(setf board-diagnosis t) 
(dotimes (ix 3) 
(dotimes (iy 3) 

(setf (aref board ix iy) *empty*))))) 



the display method for the board pane 
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(def method display-board ((frame tic-tac-toe) stream 

&key &al low-other-keys) 
(with-slots (board) frame 

(multiple-value-bind (width height) (window-inside-size stream) 
(multiple-value-bind (size x-offset y-offset) 
(if (< width height) 

(values (floor width 3) (floor (- height width) 2)) 
(values (floor height 3) (floor (- width height) 2) 0)) 
(flet ((draw-element (elt position stream) 
(cond ((= elt xXx) 

(wi th-output-as-presentati on 

(stream position 'x-board-position 
:single-box t) 
(draw-line* stream 0.1 0.1 0.9 0.9 : 1 ine-thickness 2) 
(draw-line* stream 0.1 0.9 0.9 0.1 : 1 ine-thickness 2))) 
((= elt *0*) 
(wi th-output-as-presentati on 

(stream position 'o-board-position 
:single-box t) 
(draw-circle* stream 0.5 0.5 0.45 

:filled nil : 1 ine-thickness 2))) 
(t 
(wi th-output-as-presentati on 

(stream position 'empty-board-position) 
(draw-rectangle* stream 0.1 0.1 0.9 0.9 :ink +white+)))))) 
(with-translation (stream x-offset y-offset) 
(with-scal ing (stream size size) 
(dotimes (iy 3) 

(with-translation (stream iy) 
(dotimes (ix 3) 

(let ((elt (aref board ix iy)) 

(position (+ (* 3 iy) ix))) 
(updating-output (stream :unique-id position 

: cache-value elt) 
(with-translation (stream ix 0) 

(draw-element elt position stream))))))) 
(draw-line* stream 0.1 1.0 2.9 1.0) 
(draw-line* stream 0.1 2.0 2.9 2.0) 
(draw-line* stream 1.0 0.1 1.0 2.9) 
(draw-line* stream 2.0 0.1 2.0 2.9)))))))) 

;;; the display method for the status pane 
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(def method display-status ((frame tic-tac-toe) stream 

&key &al low-other-keys) 
(with-slots (board-diagnosis) frame 

(updating-output (stream : cache-value board-diagnosis) 
(let ((string (cond ((null board-diagnosis) "Cat's game") 

((eql board-diagnosis xXx) "Win for X") 
((eql board-diagnosis xOx) "Win for 0")))) 
(when string 

(write-string string stream)))))) 

;;; make a move in the game 

(def i ne-ti c-tac-toe-command com-user-move 

((pos 'empty-board-position : gesture : select)) 
(with-slots (board whose-move board-diagnosis) xappl i cation-frame* 
(multiple-value-bind (iy ix) (floor pos 3) 

(make-move *appl i cati on-frame* ix iy)) 
(if (eql board-diagnosis t) 

(multiple-value-bind (ix iy) (f ind-next-ttt-move board whose-move) 
(make-move *appl i cation-frame* ix iy) 
(unless (eql board-diagnosis t) 

(go-to-stopped-state *appl i cati on-frame*) ) ) 
(go-to-stopped-state *appl i cati on-frame*) ) ) ) 

(defmethod make-move ((frame tic-tac-toe) ix iy) 

(with-slots (board whose-move board-diagnosis) frame 
(if (= (aref board ix iy) *empty*) 

(progn (setf (aref board ix iy) whose-move) 
(setf whose-move (- whose-move)) 
(setf board-diagnosis (diagnose-board board))) 
(error "Not an empty position")))) 

;;; edit a position by cycling through possibilities 

(def i ne-ti c-tac-toe-command com-edit-position 
((pos 'board-position :gesture :select)) 
(with-slots (board board-diagnosis) *appl i cati on-frame* 
(multiple-value-bind (iy ix) (floor pos 3) 
(setf (aref board ix iy) 

(let ((old (aref board ix iy))) 

(cond ((= old *empty*) *X*) 

((= old *X*) *0*) 

(t *empty*))))) 

(setf board-diagnosis (diagnose-board board)))) 
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(def ine-tic-tac-toe-command (com-play-user-f i rst :menu "Play (user X)") () 
(with-slots (user-plays) *appl i cati on-frame* 
(setf user-plays xXx) 
(start-pl ay xappl i cati on-frame*) ) ) 

(def ine-tic-tac-toe-command (com-play-program-f i rst :menu "Play (program X)") () 
(with-slots (user-plays) *appl i cati on-frame* 
(setf user-plays *0*) 
(start-pl ay *appl i cati on-frame*) ) ) 

(def method start-play ((frame tic-tac-toe)) 

(with-slots (board whose-move user-plays board-diagnosis) *appl i cati on-frame* 
(unless (eql board-diagnosis t) 

(reset-board *appl i cati on-frame*)) 
(go-to-pl ayi ng-state *appl i cati on-frame*) 
(setf whose-move (determine-whose-move board)) 
(when (/= user-plays whose-move) 

(multiple-value-bind (ix iy) (f ind-next-ttt-move board whose-move) 
(make-move *appl i cati on-frame* ix iy))))) 

;;; enable and disable appropriate commands 

(def method go-to-pl ayi ng-state ((frame tic-tac-toe)) 
(setf (command-enabled 'com-play-user-f i rst frame) nil) 
(setf (command-enabled 'com-play-program-f i rst frame) nil) 
(setf (command-enabled 'com-edit-position frame) nil) 
(setf (command-enabled 'com-user-move frame) t)) 

(def method go-to-stopped-state ((frame tic-tac-toe)) 
(setf (command-enabled 'com-play-user-f i rst frame) t) 
(setf (command-enabled 'com-play-program-f i rst frame) t) 
(setf (command-enabled 'com-edit-position frame) t) 
(setf (command-enabled 'com-user-move frame) nil)) 

;;; these are the game-playing functions 
;;; they have no user-interface component 

;;; picks the next move for the program 
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(defun f ind-next-ttt-move (board whose-move) 
(let ((me whose-move) (you (- whose-move))) 
(let (target (points nil)) 
(labels ((pushnu (x y) 

(unless (find-if #' (lambda (xy) 

(and (= (first xy) x) 

(= (second xy) y))) 
points) 
(push (list x y) points))) 
(point-= (p1 p2) 

(and (= (first p1) (first p2)) (= (second p1) (second p2)))) 
(pick-a-choice-if-ive-got-one () 
(when points 

(let ((ran (random (length points)))) 
(return-from f ind-next-ttt-move 
(values-list (nth ran points)))))) 
(almost-complete-row (eltB x0 y0 eltl x1 y1 elt2 x2 y2) 
(cond ((and (= eltB xemptyx) (= eltl elt2 target)) 
(pushnu x0 y0)) 
((and (= eltl *empty*) (= eltB elt2 target)) 

(pushnu x1 y1)) 
((and (= elt2 *empty*) (= eltB eltl target)) 
(pushnu x2 y2)))) 
(row-with-one-only (eltB xB yB eltl x1 y1 elt2 x2 y2) 
(cond ((and (= eltB eltl xemptyx) (= elt2 target)) 
(pushnu xB yB) 
(pushnu x1 y1)) 
((and (= eltl elt2 xemptyx) (= 
(pushnu x1 y1) 
(pushnu x2 y2)) 
((and (= eltB elt2 xemptyx) (= 
(pushnu xB yB) 
(pushnu x2 y2)))) 
(pai r-of-rows-to-fork (eltB xB yB 

eltla x1a y1a 
elt2a x2a y2a 
eltlb x1b y1b 
elt2b x2b y2b) 
(declare (ignore x1a y1a x2a y2a x1b y1b x2b y2b)) 
(when (and (= eltB xemptyx) 

(or (and (= eltla xemptyx) (= 

(and ( = 
(or (and (= 
(and ( = 
(pushnu xB yB)))) 
;; look for immediate win 
(setq target me) 



eltB target)) 



eltl target)) 



elt2a xemptyx) (= 
eltlb xemptyx) (= 
elt2b xemptyx) (= 



elt2a target)) 
eltla target))) 
elt2b target)) 
eltlb target)))) 
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(map-over-ttt-board-rows board #' almost-complete-row) 

(pick-a-choice-if-ive-got-one) 

;; look for immediate loss unless I block 

(setq target you) 

(map-over-ttt-board-rows board #' almost-complete-row) 

(pick-a-choice-if-ive-got-one) 

; ; look for my fork 

(setq target me) 

(map-over-pai rs-of-ttt-board-rows board tf'pai r-of-rows-to-fork) 

(pick-a-choice-if-ive-got-one) 

;; look for opponent's fork 

(setq target you) 

(map-over-pai rs-of-ttt-board-rows board #' pai r-of-rows-to-fork) 

(when points 

(if (= (length points) 1) 
; ; block the fork 
(pick-a-choice-if-ive-got-one) 
;; two fork points - have to force 
(let ((fork-points points)) 
(setq points nil) 

(map-over-ttt-board-rows board #' row-with-one-only) 
(setq points (set-difference points fork-points :test #'point-=)) 
(pi ck-a-choi ce-i f-i ve-got-one) ) ) ) ) ) 
;; an opening move in a corner requires a reply in the center 
;; else prefer a corner 
(when (= (aref board 1 1) xemptyx) 

(return-from f ind-next-ttt-move (values 1 1))) 
(loop for ix from to 2 by 2 do 
(loop for iy from to 2 by 2 do 

(when (= (aref board ix iy) xemptyx) 

(return-from f ind-next-ttt-move (values ix iy))))))) 

returns xX* or xO* for a winning board 

T for a board still playable, nil for a cats game 
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(defun diagnose-board (board) 

(flet ((diagnose-row (eltB xB y0 eltl x1 y1 elt2 x2 y2) 
x0 y0 x1 y1 x2 y2 

;; returns xXx or xO* for a winning row 
;; T for a row still playable, nil for a blocked row 
(cond ((= eltB eltl elt2) 

(if (= eltB *empty*) t eltB)) 
((= eltB eltl) 

(if (or (= eltB xemptyx) (= elt2 xemptyx)) t nil)) 
((= eltB elt2) 

(if (or (= eltB xemptyx) (= eltl xemptyx)) t nil)) 
((= eltl elt2) 

(if (or (= eltB xemptyx) (= eltl xemptyx)) t nil)) 
(t nil)))) 
(let ((x-win nil) (o-win nil) (cats-game t)) 
(map-over-ttt-board-rows board 
it' (lambda (eltB xB yB eltl x1 y1 elt2 x2 y2) 

(let ((q (diagnose-row eltB xB yB eltl x1 y1 elt2 x2 y2))) 
(cond ((eql q xXx) (setq x-win t)) 
((eql q xOx) (setq o-win t)) 
((eql q t) (setq cats-game nil)))))) 
(cond (x-win xXx) 
(o-win xOx) 
(cats-game nil) 
(t t))))) 

;;; used when starting the program in the middle of a game 

(defun determine-whose-move (board) 
(let ((xs B) (os B)) 
(dotimes (x 3) 
(dotimes (y 3) 

(let ((elt (aref board x y))) 
(cond ((= elt xXx) (incf xs)) 

((= elt xOx) (incf os)))))) 
(if (> xs os) xOx *X*))) 
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(defun map-over-ttt-board-rows (board function) 
(macrolet ((dorow (x0 y0 dx dy) 

(let* ((x1 (+ x0 dx)) (y1 (+ y0 dy)) 
(x2 (+ x1 dx)) (y2 (+ y1 dy))) 
(setq x2 (mod x2 3) y2 (mod y2 3)) 
1 (funcal 1 function 

(aref board ,x0 ,y0) ,x0 ,y0 
(aref board ,x1 ,y1) ,x1 ,y1 
(aref board ,x2 ,y2) ,x2 ,y2)))) 
(dorow 1) 
(dorow 10 1) 
(dorow 2 1) 
(dorow 10) 
(dorow 110) 
(dorow 2 10) 
(dorow 11) 
(dorow 2 1 -1))) 
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(defun map-over-pai rs-of-ttt-board-rows (board function) 
(macrolet ((dorows (x0 y0 dxa dya dxb dyb) 

(let* ((x1a (+ x0 dxa)) (y1a (+ y0 dya)) 
(x2a (+ x1a dxa)) (y2a (+ y1a dya)) 
(x1b (+ x0 dxb)) (y1b (+ y0 dyb)) 
(x2b (+ x1b dxb)) (y2b (+ y1b dyb))) 
(setq x2a (mod x2a 3) y2a (mod y2a 3) 

x2b (mod x2b 3) y2b (mod y2b 3)) 
1 (funcal 1 function 

(aref board ,x0 ,y0) ,x0 ,y0 
(aref board ,x1a ,y1a) ,x1a ,y1a 
(aref board ,x2a ,y2a) ,x2a ,y2a 
(aref board ,x1b ,y1b) ,x1b ,y1b 
(aref board ,x2b ,y2b) ,x2b ,y2b)))) 
(dorows 110) 
(dorows 1 1 1) 
(dorows 1 1 1) 
(dorows 1 1 1) 
(dorows 2 0-110) 
(dorows 2 0-1 1 -1) 



(dorows 
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(dorows 12 0-110) 
(dorows 2 1-10) 
(dorows 2 1 -1 1) 



(dorows 2 0-1 

(dorows 2 1 -1 

(dorows 2 2 0- 

(dorows 2 2 0- 

(dorows 2 2-1 



-1 1) 
i 1) 
-1 0) 
-1 -1) 
-1 -1))) 



tfll 



(setq ttt (cl im:make-appl ication-f rame 'tic-tac-toe 

:left 400 :right 800 :top 150 :bottom 400)) 
(cl im: run-frame-top-level ttt) 
lift 
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Code for Plotting Data 

This code can be found in the file SYS:CLIM;REL-2;TUT0RIAL;LEAST-SQUARES-1 .LISP. 

;;; -*- Mode: Lisp; Syntax: ANSI-Common-Lisp; Package: CLIM-USER; Base: 10 -x- 

(defclass data-point () 

((x :accessor point-x :initarg :x) 
(y :accessor point-y :initarg :y))) 

(defun make-data-point (x y) 

(make-instance 'data-point :x x :y y)) 

(def ine-presentati on-type data-point ()) 
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(def ine-appl i cation-frame lsq () 
((data-points :initform nil) 
(data-points-tick :initform 0) 
(data-x-min :initform 0.0) 
(data-x-max :initform 1.0) 
(data-y-min :initform 0.0) 
(data-y-max :initform 1.0) 
(data-left-margin) 
(data-top-margi n) 
(data-right-margin) 
(data-bottom-margi n) 
(data-transform) 
(current-curve :initform nil) 
(curve-correlation) 

(current-coefficients :initform (make-array 25 : f il 1-pointer t)) 
(x-is-function-of-y :initform nil)) 
(: command-table (lsq : inherit-f rom (accept-values-pane))) 
( : panes 

(display : application 

: di spl ay-f uncti on ' draw-data-di spl ay 
: incremental-redisplay t 
: display-after-commands t 
: scroll -bars nil) 
(table : application 

: incremental-redisplay t 
:scroll-bars :vertical 
: di spl ay-f uncti on ' tabul ate-data-poi nts) 
(equation : application 

: display- function 'print-equation-of -curve 
: display-after-commands t 
: incremental-redisplay t 
: scroll -bars nil)) 
( : layouts 

(drawing-layout 

(vertically () display)) 
(tabular-layout 

(vertically () (7/8 table) (1/8 equation))))) 



initial izations 



(defmethod frame-standard-output ((frame lsq)) 

(if (eql (frame-current-layout frame) 'drawing-layout) 
(get-frame-pane frame 'display) 
(get-frame-pane frame 'table))) 
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(def method frame-standard-input ((frame lsq)) 
(frame-standard-output frame)) 

(defmethod f rame-query-io ((frame lsq)) 
(frame-standard-output frame)) 

(defmethod run-frame-top-level : before ((frame lsq) &key) 
(enable-f rame frame) 
(assign-margins-for-axes frame) 
(determi ne-data-transf orm frame) ) 

;;; switching layouts 

(def ine-lsq-command (switch-configurations :menu "Switch Display") () 
(let ((frame xappl i cation-frame*)) 

(let ((new-config (case (frame-current-layout frame) 
(drawing-layout 

(setf (command-enabled 'com-zoom-in frame) nil) 
(setf (command-enabled 'com-zoom-out frame) nil) 
'tabular-layout) 
(tabular-layout 

(setf (command-enabled 'com-zoom-in frame) t) 
(setf (command-enabled 'com-zoom-out frame) t) 
' drawi ng-1 ay out) ) ) ) 
(setf (frame-current-layout frame) new-config)))) 

;;; adding new points, deleting points 
;;; points are maintained in sorted order: 

(defun point< (pointl point2) 

(let ((x1 (point-x pointl)) (x2 (point-x point2))) 
(cond ((< x1 x2) t) 

((= x1 x2) (< (point-y pointl) (point-y point2)))))) 

(defmethod add-data-point ((point data-point) (frame lsq)) 
(with-slots (data-points-tick data-points) frame 

(setf data-points (merge 'list data-points (list point) #'point<)) 
(incf data-points-tick))) 

(defmethod delete-data-point ((point data-point) (frame lsq)) 

(with-slots (data-points-tick data-points dummy-data-points) frame 
(setf data-points (delete point data-points)) 
(incf data-points-tick))) 
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(defmethod al ter-data-point ((point data-point) (frame lsq) x y) 
(with-slots (data-points-tick data-points dummy-data-points) frame 
(setf (point-x point) x) 
(setf (point-y point) y) 

(setf data-points (sort data-points #'point<)) 
(incf data-points-tick))) 

; ; ; table display 

(defmethod tabulate-data-points ((frame lsq) pane &key &al low-other-keys) 
(f resh-1 ine pane) 
(flet ((do-point (point stream) 

(with-output-as-presentation (stream point 'data-point 

:single-box t) 
(formatting-row (stream) 
(formatting-cel 1 (stream) 

(format stream "~F" (point-x point))) 
(formatting-cel 1 (stream) 

(format stream "~F" (point-y point))))))) 
(formatting-table (pane) 
;; print column headings 
(formatting-row (pane) 

(with-text-face (pane : italic) 

(formatting-cel 1 (pane :min-width 20 

:align-x :center) 
(write-string "X" pane)) 
(formatting-cel 1 (pane :min-width 20 

:align-x :center) 
(write-string "Y" pane)))) 
(with-slots (data-points) frame 
(dolist (point data-points) 
(do-point point pane)))))) 

; ; ; graphic display 
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(def method draw-data-display ((frame lsq) pane &key &al low-other-keys) 
(with-slots (current-curve current-coefficients x-is-function-of-y 

data-x-min data-x-max data-y-min data-y-max data-points-tick 
data-right-margin data-left-margin data-transform) 
frame 
(draw-data-axes frame pane) 
(updating-output (pane :unique-id ':the-curve 

: cache-value data-points-tick 
:cache-test #'=) 
(draw-data-points frame pane) 
(when current-curve 

(with-drawing-options (pane : transformation data-transform) 
(draw-f itted-curve current-curve current-coefficients pane 

data-x-min data-x-max data-y-min data-y-max 
(- data-right-margin data-left-margin) 
x-i s-f uncti on-of-y) ) ) ) ) ) 

;;; methods on the data points 

(defmethod data-range ((frame lsq)) 
(with-slots (data-points) frame 

(let* ((min-x (point-x (first data-points))) 
(max-x min-x) 

(min-y (point-y (first data-points))) 
(max-y min-y)) 
(dolist (point (rest data-points)) 
(macrolet ((maxminf (val min max) 
l (let ((v ,val)) 

(cond ((< v ,min) (setq ,min v)) 

((> v , max) (setq , max v)))))) 
(maxminf (point-x point) min-x max-x) 
(maxminf (point-y point) min-y max-y))) 
(values min-x min-y max-x max-y)))) 
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(def method determine-data-transform ((frame lsq) 

&optional left top right bottom) 
(with-slots (data-left-margin data-top-margin 

data-ri ght-margi n data-bottom-margi n 
data-x-min data-x-max data-y-min data-y-max 
data-transform data-points-tick) frame 
(when (null left) (setq left data-left-margin)) 
(when (null top) (setq top data-top-margin)) 
(when (null right) (setq right data-right-margin)) 
(when (null bottom) (setq bottom data-bottom-margin)) 
(setf data-transform 

(make-3-poi nt-transf ormati on* 
data-x-min data-y-min 
data-x-min data-y-max 
data-x-max data-y-min 
left bottom 
left top 
right bottom)) 
(incf data-points-tick))) 
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(def ine-lsq-command (com-set-axis-ranges :menu t) 


(let ((frame xappl i cation-frame*) 
(stream xstandard-outputx)) 
(with-slots (data-x-min data-x-max data-y-min data-y-max 

data-points data-transform data-points-tick) frame 
(incf data-points-tick) 
(let ((min-x data-x-min) 
(max-x data-x-max) 
(min-y data-y-min) 
(max-y data-y-max)) 
(accepti ng-val ues 
(stream 

:own-window '(: right-margin (20 :character)) 
:label "Enter the ranges for the coordinate axes") 
(format stream "~&Range of X axis: ") 
(flet ((get-one (value id) 
(accept 'real 

: stream stream 
: default value 
:query-identif ier id 
: prompt nil))) 
(setq min-x (get-one min-x 'x-min)) 
(format stream " to ") 
(setq max-x (get-one max-x 'x-max)) 
(format stream "~&Range of Y axis: ") 
(setq min-y (get-one min-y 'y-min)) 
(format stream " to ") 
(setq max-y (get-one max-y 'y-max))) 
(fresh-line stream) 
(terpri stream) 
(accept-val ues-command-button 

(stream :query-identif ier 'al 1-of-them) 

"Set ranges to encompass all points" 
(mul tiple-value-setq (min-x min-y max-x max-y) 
(data-range frame))) 
(fresh-line stream) 
(terpri stream)) 
(setq data-x-min min-x 
data-x-max max-x 
data-y-min min-y 
data-y-max max-y)) 
(determi ne-data-transf orm frame) ) ) ) 
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(def method draw-data-points ((frame lsq) pane) 

(with-slots (data-points data-points-tick data-transform 

data-x-min data-x-max data-y-min data-y-max) frame 
(flet ((do-point (point window) 

(let ((x (point-x point)) (y (point-y point))) 
(when (and (<= data-x-min x data-x-max) 
(<= data-y-min x data-y-max)) 
(with-output-as-presentation (window point 'data-point) 
(multiple-value-bind (x y) 

(transform-position data-transform x y) 
(draw-circle* window x y 3))))))) 
(dolist (point data-points) 
(do-point point pane))))) 

(def ine-lsq-command com-create-data-point ((x 'real) (y 'real)) 
(add-data-point (make-data-point x y) *appl i cation-frame*)) 

(def ine-presen tat ion-to-command- translator new-point 
(blank-area com-create-data-point lsq 
: gesture : select 
: tester 

((x y window) 
(let ((frame *appl i cation-frame*)) 

(with-slots (data-left-margin data-top-margin 

data-right-margin data-bottom-margin) frame 
(and (eql window (get-frame-pane frame 'display)) 
(<= data-left-margin x data-right-margin) 
(<= data-top-margin y data-bottom-margin)))))) 

(x y) 

(with-slots (data-transform) *appl i cation-frame* 
(multiple-value-bind (x y) 

(untransform-position data-transform x y) 
(list x y)))) 

(def i ne-1 sq-command corn-del ete-data-poi nt 
((point 'data-point :gesture :delete)) 
(del ete-data-poi nt point *appl i cation-frame*)) 
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(def i ne-1 sq-command com-edi t-data-poi nt 
((point 'data-point :gesture :edit)) 
(let ((x (point-x point)) 
(y (point-y point)) 
(stream xstandard-outputx)) 
(accepti ng-val ues 
(stream 

:own-window '(: right-margin (20 :character)) 
:label "New coordinates for the point") 
(fresh-line stream) 
(setq x (accept 'real 

: stream stream 
: prompt "X: " 
:default x)) 
(fresh-line stream) 
(setq y (accept 'real 

: stream stream 
: prompt "Y: " 
: default y))) 
(al ter-data-point point xappl i cation-frame* x y))) 

\ j j 3X6S 

(defmethod draw-data-axes ((frame lsq) pane) 

(with-slots (data-x-min data-x-max data-y-max data-y-min 

data-transform 

data-left-margin data-top-margin 
data-ri ght-margi n data-bottom-margi n) 
frame 
(flet ((pair= (pairl pair2) 

(and (= (car pairl) (car pair2)) 

(= (cdr pairl) (cdr pair2))))) 
(declare (dynamic-extent #'pair=)) 
(updating-output (pane :unique-id 'x-axis 

: cache-value (cons data-x-min data-x-max) 
:cache-test #'pair=) 
(draw-horizontal -axis pane data-x-min data-x-max 

data-transform 

data-1 ef t-margi n data-ri ght-margi n 
data-bottom-margi n) ) 
(updating-output (pane :unique-id 'y-axis 

: cache-value (cons data-y-max data-y-min) 
:cache-test #'pair=) 
(draw-vertical -axis pane data-y-min data-y-max data-transform 
data-left-margin data-top-margin 
data-bottom-margi n) ) ) ) ) 
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(defvar xhorizontal -scale-mark-density* 80) 

(defun draw-horizontal -axis (window data-mi n data-max data-transform 

view-x-min view-x-max view-y) 
(let* ((tick-end view-y) 

(tick-start (+ tick-end 8)) 
(text-top (+ tick-start 2))) 
(draw-line* window view-x-min view-y view-x-max view-y) 
(flet ((drawer (x) 

(multiple-value-bind (vx vy) 

(transform-position data-transform x 0.0) 

(draw-line* window vx tick-start vx tick-end) 
(draw-text* window (format nil "~jf" x) vx text-top 
:align-x : center :align-y :top)))) 
(declare (dynamic-extent tf'drawer)) 
(axis-iterator data-min 
data-max 
tf'drawer 
(max (round (- view-x-max view-x-min) 

*horizontal -scale-mark-density*) 
D)))) 

(defvar *vertical -scale-mark-density* 50) 

(defun draw-vertical -axis (window data-min data-max data-transform 

view-x view-y-min view-y-max) 
(let* ((tick-end view-x) 

(tick-start (- tick-end 8)) 
(text-end (- tick-start 2))) 
(draw-line* window view-x view-y-min view-x view-y-max) 
(flet ((drawer (y) 

(multiple-value-bind (vx vy) 

(transform-position data-transform 0.0 y) 
vx 

(draw-line* window tick-start vy tick-end vy) 
(draw-text* window (format nil "~jf" y) text-end vy 
:align-x :right :align-y :center)))) 
(declare (dynamic-extent tf'drawer)) 
(axis-iterator data-min 
data-max 
tf'drawer 
(max (round (- view-y-max view-y-min) 

*verti cal -seal e-mark-densi ty*) 
D)))) 
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(defun axis-iterator (min-val max-val drawit approx-number-of-steps) 
(let* ((step (float (stepsize-for-scale min-val max-val 

approx-number-of-steps) ) ) 
(i0 (ceiling min-val step)) 
(i1 (floor max-val step))) 
(loop for i from i0 to i1 do (funcall drawit (* i step))))) 

(defun stepsize-for-scale (datamin datamax approx-number-of-steps) 
(declare (values stepsize mantissa)) 
(assert (< datamin datamax)) 

(let* ((step (/ (- datamax datamin) approx-number-of-steps)) 
(step-exponent (expt 10 (floor (log step 10)))) 
(step-mantissa (/ step step-exponent))) 
;; at this point 1 <= step-mantissa < 10 
;; we choose nearest (logarithmically) to 1, 2, or 5 
(cond ((< step-mantissa (sqrt 2)) (values step-exponent 1)) 

((< step-mantissa (sqrt 5/2)) (values (* 2 step-exponent) 2)) 
((< step-mantissa (* 5.0 (sqrt 2))) 

(values (* 5 step-exponent) 5)) 
(t (values (* 10 step-exponent) 1))))) 

(def method assign-margins-for-axes ((frame lsq)) 
(with-slots (data-left-margin data-top-margin 

data-right-margin data-bottom-margin) frame 
(let* ((display (get-frame-pane frame 'display)) 

(typical-text (with-output-to-output-record (display) 
(format display "~7F" 123.456)))) 
(multiple-value-bind (width height) 

(bounding-rectangle-size (window-viewport display)) 
(setf data-left-margin 

(+ 10 (bounding-rectangle-width typical -text))) 
(setf data-top-margin 

( bound i ng-rectangl e-hei ght typi cal -text) ) 
(setf data-right-margin 

(- width (bounding-rectangle-width typi cal -text))) 
(setf data-bottom-margin 
(- height 

(+ 10 (bounding-rectangle-height typical-text)))))))) 

;;; linear algebra utilities 

;;; solves a lower triangular system 
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(defun sol ve-lower-tri (1 x) 
(let ((ii (length x))) 
(dotimes (i ii) 

(let ((xi (aref x i))) 
(dotimes (j i) 

(decf xi (x (aref 1 i j) (aref x j)))) 
(setf (aref x i) (/ xi (aref 1 i i))))) 
x)) 

;;; solves an upper triangular system stored in transposed form 

(defun sol ve-upper-tri -trans (u x) 
(let ((ii (length x))) 

(do* ((i (1- ii) (1- i))) ((< i 0)) 
(let ((xi (aref x i))) 

(do ((j (1+ i) (1+ j))) ((= j ii)) 

(decf xi (x (aref u j i) (aref x j)))) 
(setf (aref x i) (/ xi (aref u i i))))) 
x)) 

;;; in-place Cholesky decomposition of a positive definite matrix 

(defun cholesky (a) 

(let ((n (array-dimension a 0))) 
(dotimes (k n) 

(let ((akk (aref a k k))) 

(dotimes (j k) (decf akk (expt (aref a k j) 2))) 

(setq akk (sqrt akk)) ;told you it must be positive definite 

(setf (aref akk) akk) 
(do ((i (1+ k) (1+ i))) ((= i n)) 
(let ((aik (aref a i k))) 

(dotimes (j k) (decf aik (x (aref a i j) (aref a k j)))) 
(setf (aref a i k) (/ aik akk))))))) 
a) 

; ; ; least squares 
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(defun general-linear-regression (value-mapper functions &optional 

result (compute-correlation t)) 
(let* ((n-coef (length functions)) 
(fx (make-array n-coef)) 
(dims (list n-coef n-coef)) 
(a (make-array dims : initial-element 0))) 
(declare (dynamic-extent fx dims a)) 
(if (and (arrayp result) 

(or (= (array-dimension result 0) n-coef) 

(and (> (array-dimension result 0) n-coef) 
(ar ray-has- f il 1-pointer-p result)))) 
(progn (dotimes (i n-coef) (setf (aref result i) 0.0)) 
(if (array-has-f il 1-pointer-p result) 

(setf (fill-pointer result) n-coef))) 
(setq result (make-array n-coef : initial-element 0.0))) 
(flet ( (total -up-values (yi &rest xs) 
(let ((functions functions)) 
(dotimes (i n-coef) 

(setf (aref fx i) (apply (pop functions) xs)))) 
(dotimes (i n-coef) 

(let ((fxi (aref fx i))) 

(incf (aref a i i) (* fxi fxi)) 
(incf (aref result i) (* fxi yi)) 
(do ((j (1+ i) (1+ j))) 
((= j n-coef)) 
(let* ((fxj (aref fx j)) (fxi-fxj (* fxi fxj))) 
(incf (aref a i j) fxi-fxj) 
(incf (aref a j i) fxi-fxj))))))) 
(declare (dynamic-extent #' total -up-values)) 
(funcall value-mapper tf'total-up-values)) 
(cholesky a) 

(sol ve-lower-tri a result) 
(sol ve-upper-tri-trans a result) 
(if compute-correlation 
(let ((n 0) 

(sum-y 0.0) 
(sum-y2 0.0) 
(sum-fx 0.0) 
(sum-fx2 0.0)) 
(flet ((calc-correlation (yi &rest xs) 
(let ((fxi (do ((j (1+ j)) 

(functions functions) 
(sum 0.0)) 
((null functions) sum) 
(incf sum (* (aref result j) 

(apply (pop functions) 
xs)))))) 
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(incf n) 
(incf sum-y yi) 
(incf sum-y2 (* yi yi)) 
(incf sum-fx fxi) 
(incf sum-fx2 (* fxi fxi))))) 
(declare (dynamic-extent #'calc-correlation)) 
(funcall value-mapper #'calc-correlation)) 
(values result (/ (+ sum-fx2 (* (/ sum-y n) 

(- sum-y (* 2 sum-fx)))) 
(- sum-y2 (/ (* sum-y sum-y) n))))) 
result))) 

; ; ; curves to fit 

(defclass fit-curve () 

((name : accessor curve-name :initarg :name) 
(n-coefs :accessor curve-n-coefs :initarg :n-coefs) 
(component-functions :initarg :component-functions) 
(printer :initarg :printer :accessor curve-printer))) 

(defclass linear-fit-curve (fit-curve) ()) 

(defmethod function-value ((fit-curve fit-curve) coefficients 

&rest i ndependent-vari abl e-val ues) 
(declare (dynamic-extent independent-variable-values)) 
(with-slots (component-functions n-coefs) fit-curve 
(let ((total 0.0) (components component-functions)) 
(dotimes (i n-coefs) 
(incf total 

(* (aref coefficients i) 

(apply (pop components) independent-variable-values)))) 
total))) 

(defmethod least-squares-fit ((fit-curve fit-curve) value-mapper coefficients) 
(with-slots (component-functions n-coefs) fit-curve 
(assert (>= (array-dimension coefficients 0) n-coefs)) 
(general -1 i near- regress ion value-mapper 

component- functions 
coefficients))) 



;;; utility component-functions 

(defun unity (&rest args) (declare (ignore args)) 1) 

(defun square (x) (* x x)) 

(defun cube (x) (expt x 3)) 
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the curves that are fitted 



(defvar xknown-curvesx nil) 



(defun def-f it-curve (name &key component-functions printer 

(curve-class 'fit-curve)) 
(setq xknown-curvesx (delete name xknown-curvesx 

:test #'string-equal 
:key #'curve-name)) 
(assert (listp component-functions)) 
(let ((n-coefs (length component-functions))) 
(push (make-instance curve-class 

:name name 
: n-coefs n-coefs 

: component- functions component- functions 
:printer printer) 
xknown-curvesx) ) ) 



(def-f it-curve "Cubic" 

:component-functions (list #'cube #'square ^'identity #'unity) 
:printer #' (lambda (stream var coefs) 

(format stream "~7F ~A~3 + ~7F ~A~2 + ~7F ~A + ~7F" 
(elt coefs 0) var (elt coefs 1) var 
(elt coefs 2) var (elt coefs 3)))) 

(def-f it-curve "Quadratic" 

:component-functions (list #'square ^'identity #'unity) 
:printer #' (lambda (stream var coefs) 

(format stream "~7F ~A~2 + ~7F ~A + ~7F" 

(elt coefs 0) var (elt coefs 1) var 
(elt coefs 2)))) 



(def-f it-curve "Linear" 

:curve-class 'linear-fit-curve 
:component-functions (list ^'identity tf'unity) 
:printer ft' (lambda (stream var coefs) 

(format stream "~7F ~A + ~7F" (elt coefs 0) var 
(elt coefs 1)))) 



; ; ; curve display 

;;; the default method of drawing curves 
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(defmethod draw-f itted-curve ((curve fit-curve) coefficients pane 

data-x-min data-x-max data-y-min data-y-max 
n-plotting-steps x-is-function-of-y) 
(labels ((plotter (umin umax vmin vmax drawer) 

(let ((du (/ (- umax umin) n-plotting-steps))) 
(do* ((u0 nil u1) 
(v0 nil v1) 
(u1 umin (+ u1 du)) 

(v1 (function-value curve coefficients u1) 
(function-value curve coefficients u1))) 
((> u1 umax)) 
(when (and u0 

(<= vmin v0 vmax) 
(<= vmin v1 vmax)) 
(funcall drawer u0 v0 u1 v1))))) 
(y=fx-drawer (u0 v0 u1 v1) 

(draw-line* pane u0 v0 u1 v1)) 
(x=fy-drawer (u0 v0 u1 v1) 

(draw-line* pane v0 u0 v1 u1))) 
(declare (dynamic-extent #'y=fx-drawer #'x=fy-drawer)) 
(if x-is-function-of-y 

(plotter data-y-min data-y-max data-x-min data-x-max #'x=fy-drawer) 
(plotter data-x-min data-x-max data-y-min data-y-max #'y=fx-drawer)))) 

;;; the 1 i near-f i t-curve class has a faster method of drawing 
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(defmethod draw-f itted-curve ((curve linear-fit-curve) coefficients pane 

data-x-min data-x-max data-y-min data-y-max 
n-plotting-steps x-is-function-of-y) 
(declare (ignore n-plotting-steps)) 
(labels ((linterp (x x0 x1 y0 y1) 

(let ((d0 (- x x0)) (d1 (- x1 x))) 

(/ (+ (* d0 y1) (* d1 y0)) (+ d0 d1)))) 
(plotter (umin umax vmin vmax drawer) 
(let ((u0 umin) 

(v0 (function-value curve coefficients umin)) 
(u1 umax) 

(v1 (function-value curve coefficients umax))) 
(macrolet ((v-clip (« vlimit) 

1 (if (,« v0 , vlimit) 

(if (,« v1 , vl imit) 

(return-from plotter) 

(setq u0 (linterp , vlimit v0 v1 umin umax) 
v0 , vlimit)) 
(if (,« v1 , vl imit) 

(setq u1 (linterp , vlimit v0 v1 umin umax) 
v1 , vlimit))))) 
(v-cl ip < vmin) 
(v-cl ip > vmax)) 
(funcall drawer u0 v0 u1 v1))) 
(y=fx-drawer (u0 v0 u1 v1) 

(draw-line* pane u0 v0 u1 v1)) 
(x=fy-drawer (u0 v0 u1 v1) 

(draw-line* pane v0 u0 v1 u1))) 
(declare (dynamic-extent #'y=fx-drawer #'x=fy-drawer)) 
(if x-is-function-of-y 

(plotter data-y-min data-y-max data-x-min data-x-max #'x=fy-drawer) 
(plotter data-x-min data-x-max data-y-min data-y-max #'y=fx-drawer)))) 



; ; ; curve printing 
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(def method print-equation-of-curve ((frame lsq) pane &key &al low-other-keys) 
(with-slots (current-curve x-is-function-of-y data-points-tick 
current-coefficients curve-correlation) frame 
(updating-output (pane :unique-id ' :printed-equation 

:cache-value (cons current-curve data-points-tick)) 
(when current-curve 

(multiple-value-bind (dep-var ind-var) 

(if x-is-function-of-y (values "X" "Y") (values "Y" "X")) 
(format pane "~A = " dep-var) 

(funcall (curve-printer current-curve) pane ind-var current-coefficients) 
(format pane "~& Correlation: ~7F ~& " curve-correlation)))))) 

;;; interface to least-squares 

(def ine-lsq-command (com-f it-curve :menu "Fit Curve") 


(fit-curve xappl i cation-frame*)) 

;;; modifying the data set invalidates the least squares fit 

(def method add-data-point : after ((point data-point) (frame lsq)) 
(with-slots (current-curve) frame 
(setf current-curve nil))) 

(defmethod delete-data-point :after ((point data-point) (frame lsq)) 
(with-slots (current-curve) frame 
(setf current-curve nil))) 

;;; here's where we can control y-as-function-of-x vs x-as-function-of-y 
;;; and limited data-sets, and other variables, etc by constructing the 
;;; appropriate mapper 
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(defmethod fit-curve ((frame lsq)) 

(with-slots (current-curve current-coefficients curve-correlation 

data-points data-points-tick x-is-function-of-y) frame 
(incf data-points-tick) 
(setf current-curve 

(menu-choose xknown-curvesx 

:label "Curve to Fit" 

:printer #' (lambda (curve stream) 

(write-string (curve-name curve) stream)))) 
(when current-curve 

(if (>= (length data-points) (curve-n-coefs current-curve)) 
(flet ((y-as-function-of-x-value-mapper (function) 
(dolist (point data-points) 

(funcall function (point-y point) (point-x point)))) 
(x-as-function-of-y- value-mapper (function) 
(dolist (point data-points) 

(funcall function (point-x point) (point-y point))))) 
(declare (dynamic-extent tf'y-as-function-of-x-value-mapper 

tf'x-as-function-of-y-value-mapper)) 
(mul tiple-value-setq (current-coefficients curve-correlation) 
(least-squares-fit current-curve 

(if x-is-function-of-y 

#' x-as-function-of-y- value-mapper 
tf'y-as-function-of-x- value-mapper) 
current-coefficients))) 
(progn 

(notify-user frame 

(format nil "Not enough data points to fit a ~A function" 
(curve-name current-curve))) 
(setq current-curve nil)))))) 

(def ine-lsq-command (com-exit-lsq :menu "Exit") 


(frame-exit xappl i cation- frame*)) 

tfll 



(setq xlsqx (make-application-frame 'lsq 

:height 500 :width 500)) 
(run-frame-top-level xlsqx) 
lift 



CLIM User's Guide 
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Using Symbolics CLIM 



Using CLIM in Genera 

For more information on getting started, see the section "Running a CLIM Appli- 
cation". 

Also, see the section "Using CLIM in CLOE Developer", and see the section "Using 
the CLIM Demos". 

First, you must load the CLIM systems. Note that you must load the system CLIM 
before you can load GENERA-CLIM, CLX-CLIM, or POSTSCRIPT-CLIM. 



Command 
Command 
Command 
Command 



Load System CLIM 

Load System GENERA-CLIM ;if you want the Genera port 

Load System CLX-CLIM ;if you want the CLX port 

Load System POSTSCRIPT-CLIM ;if you want the PostScript port 



Note: The CLX port of CLIM is not currently a supported port of CLIM under 
Genera. It exists only as a sample port for people who are interested in perhaps 
implementing a port of their own. 

Using the Debugger with CLIM 

If you enter the Debugger with a full-screen CLIM window, you will see a pop-up 
notification such as "Process CAD Demo 1 got an error". This is normal, since the 
Debugger cannot display itself on the CLIM window. To enable the Debugger dis- 
play (so you can find out about the error), you should select the Listener window. 
Usually this is straightforward (for example, by clicking on the pop-up window). 

Once you have finished debugging and want to return to the CLIM window, you 
can press FUNCTION S. Another way to return to the CLIM window is to use the 
[Sel ect] command from the System Menu. CLIM windows made by application 
frames appear in the menu with the name of the application. 

In some cases, after you have finished experimenting with your application in the 
Debugger, you need to restore the application to a running state before reselecting 
the CLIM window. If you are offered a top-level restart for the application, that 
can work well. Otherwise, you can try to return from a com-your-command frame, 
if one happens to be in your stack. 

For small experiments (such as running some example code from the documenta- 
tion), you might try creating a small Lisp Listener so that both the experimental 
CLIM window and the Lisp Listener on which the Debugger will appear are both 
exposed and non-overlapping. 

To do this, use the System Menu commands (available by clicking sh -Right) to 
move, reshape, and expand the windows so that both are exposed. For example, 
when you are in Lisp Listener, choose [Reshape] from the System Menu to make 
the Lisp Listener window smaller. Then create the CLIM application frame. You 
can use the [Move] command to move one of the windows so it does not overlap 
the other. You can use the [Expand] command to make one of the windows take up 
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the space not occupied by the other window, so that the windows together take up 
the whole screen. 

You can easily switch from one window to the other by clicking Left on a window. 
You can use the Lisp Listener window to use the Debugger, and use the CLIM 
window to experiment with CLIM code. 



Using CLIM with a Color Screen in Genera 

In order to use CLIM on a "two headed" color system under Genera, you must 
first find the color screen to use. Use color:find-color-screen to do this. Then call 
clim:find-port to make a CLIM port, using the screen returned by colorrfind- 
color-screen. 

When you create an application frame, specify the port that corresponds to the 
color screen as the port. For example, you can run the CLIM Lisp Listener on a 
color screen as follows: 

(cl im : run-f rame-top-1 evel 

(cl im-demo: :do-l isp-1 istener 
:port (cl im: find-port 

: server-path l (:genera :screen , (color : find-color-screen))))) 

If you are using CLIM on a machine that has "native" color support (such as a 
color Maclvory or a color DEC Alpha AXP or UX400/UX1200), you don't need to do 
anything special. CLIM will notice that the display supports color, and it will sim- 
ply work as expected. 



Using CLIM in CLOE 

This section describes how to use CLIM in Cloe Runtime, and in Cloe Developer. 
It also describes how to run the CLIM demos in Cloe. 

For information on how to run CLIM in Genera, see the section "Using CLIM in 
Genera". 



Using CLIM in CLOE Runtime 

Cloe and CLIM runs with MS-DOS 3.3 or later, and with Microsoft Windows 3.0 in 
STANDARD mode. The Cloe Developer runs with Genera 8.1 and uses CLIM 1.0. 

Getting Started 

Use the following procedure to start up CLIM. Note that you must start up CLIM 
from MS-DOS (that is, you cannot start up CLIM from within Windows). Also note 
that you can save these commands in a Lisp startup file (init.l is loaded automati- 
cally at startup). 

1. Get into the DOS directory containing the CLIM files. 
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2. Enter the following command to start up Cloe with CLIM embedded. 

cloecl im 

3. (Optional) Set win::*winfe-exe* to a string that points to the winfe.exe file. 
For example: 

(setq win: :*winfe-exex "c:\\cl imWwinfe.exe") 

If winfe.exe is in your current working directory, or in a directory specified 
in your PATH shell variable, you do not need to set this special variable in 
Cloe. 

If you do not set this variable, Cloe will search for the file based on the path 
directory for MS-DOS. 

4. To start up MS Windows evaluate the following Lisp form: 

(wi n : start-wi ndows) 

or create a CLIM port: 

(cl im: find-port : server-path '(:cloe)) 

You will be in a terminal WINFE (Window Front End) window. Note that this 
window wraps when you fill the screen (it does not scroll). 

You can now run your CLIM application. Note that you can compile, write, or load 
CLIM files anytime, but you must have MS Windows running to run the CLIM 
code. 

Running CLIM Applications 

Note that when you are running a CLIM application in Cloe: 

• CLIM applications usually fill the whole screen. 

• You must have the input focus to type to a window. (The window title bar is 
highlighted for a window with input focus.) Click in a window to give it the in- 
put focus. 

• You can type c-C anytime to cause a break and set the input focus back to the 
Cloe Front End window. This causes the Cloe Front End window to come to the 
top, and to be de-iconified if necessary. (To continue after a break use the de- 
bugger Continue option.) 

• With Windows running, you can switch between the MS-DOS executive and 
CLIM using the standard Windows commands. You can also run any other Win- 
dows program, as long as it doesn't use memory already used by Cloe (most 
Windows programs don't). See Microsoft Windows User Guide by Microsoft Cor- 
poration. 
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For more information, see the section "Running a CLIM Application". 

Exiting from CLIM 

Use one of the following methods to exit from CLIM after Windows has started 
up. 

• Use the [Close] option from the leftmost pulldown menu 

• Press RLT-F4 once (to exit Cloe), then again (to exit from Windows), and press 
RETURN (to confirm). 

Do not use (exit). Windows acts as a subprocess of Cloe (since it was activated 
after Cloe). If Cloe exits, the Windows process hangs and you must reboot the ma- 
chine. 

Using CLIM in CLOE Developer 

CLIM is not a system that application developers need to migrate. Symbolics sup- 
plies a Cloe Runtime image with CLIM built in. Therefore, we recommend Cloe 
Developer users load CLIM into a regular Genera listener, and then access CLIM 
from Cloe. 

Getting Started 

First, in a Genera Lisp Listener, give the following commands: 

Load System CLIM 

Load System GENERA-CLIM ;if you want the Genera port 

Load System POSTSCRIPT-CLIM ;if you want the PostScript port 

Load System CLIM-DEMO ;if you want the CLIM demos 

Next, in the Cloe Listener, give the following command: 

Make CLIM Available 

Using the Debugger with CLIM under the Cloe Developer 

While experimenting with CLIM or debugging a CLIM application, if you go into 
the Debugger, the Debugger cannot be displayed on a CLIM window. Assuming 
that a CLIM window is exposed when the error happens, we recommend the fol- 
lowing two-window approach. 

For small experiments (such as running some example code from the documenta- 
tion), we recommend you resize the Cloe Listener so that both the experimental 
CLIM window and the Cloe Listener (on which the Debugger will appear) are both 
exposed and non-overlapping. 

To do this, use the System Menu commands (available by clicking sh -Right) to 
move, reshape, and expand the windows so that both are exposed. For example, 
when you are in the Cloe Listener, choose Reshape from the System Menu to make 
the Cloe Listener window smaller. Then create the CLIM window. You can use the 
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Move command to move one of the windows so it does not overlap the other. You 
can use the Expand command to make one of the windows take up the space not 
occupied by the other window, so that the windows together take up the whole 
screen. 

You can easily switch from one window to the other by clicking Left on a window. 
You can use the Cloe Lisp Listener window to use the Debugger, and use the 
CLIM window to experiment with CLIM code. 

For experiments with program frames (where you usually want to see a full-screen 
version of your program), the two-window strategy may not be appropriate. For 
these applications, you should consider the size of the window on the 386 PC. A 
standard VGA screen is 640 horizontal by 480 vertical pixels. If you use these val- 
ues to size the application, you can still use the two-window approach. If you ex- 
pect your 386-based users to use 800x600 or 1024x768 resolution, you should use 
the full screen technique described in "Using CLIM in Genera" 



Setting up Your Packages to Use CLIM 

You can use any of the following approaches for setting up your packages to use 
CLIM. Using these approaches will give a high likelihood that your application can 
be ported from one Common Lisp platform to another with minimal effort. 

• Use an explicit clim: package prefix whenever referencing a symbol in CLIM, 
and define your package as usual. 

• Define your package to inherit from the clim and clim-lisp packages. 

For example, 

(defpackage clim-user 
( :use cl im-1 isp cl im)) 

Note that you must inherit from both packages. The clim-lisp package provides 
an implementation of Common Lisp that is similar to the draft ANSI standard, 
with modifications to work with CLIM. 

• Define a package that inherits from the Common Lisp dialect of your choice and 
from the clim package. 

For example, 
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(defpackage another-cl im-user 
(:use clim common-lisp) 
#-Cloe-Runtime 
(: shadowing- import 

cl im: input-stream-p 

cl im : output-stream-p 

cl im : open-stream-p 

cl im:streamp 

cl im : stream-el ement-type 

cl im:close 

cl im: pathname 

cl im: truename)) 

Note that you may need to use shadowing to resolve conflicts (the exact set of 
conflicts will vary depending on what other package you inherit from). 



Converting from Dynamic Windows to CLIM 

The Dynamic Windows to CLIM conversion tool is a series of special-purpose 
Zmacs commands that can save you time and effort in editing large pieces of Dy- 
namic Windows code in ways that can be done semi-automatically. 

Note: these conversion tools are supported only in Genera. 

Depending on the complexity of your Dynamic Windows code, these tools may or 
may not perform the conversion completely. You will probably need to perform ad- 
ditional editing of your Dynamic Windows programs in order to generate working 
CLIM programs. The closer your Dynamic Windows source program is to standard 
Dynamic Windows, the more automatic the conversion process will be. 

For more information on conversion tools in general, see the section "Conversion 
Tools". 

Though using the conversion tool is simple, the conversion task is not. For this 
reason you must use the conversion tool with knowledge and care. 

Prerequisites 

• You should be sufficiently comfortable with both Dynamic Windows and CLIM 
systems to be aware of function equivalences and to understand the possible ef- 
fects of a conversion (such as a changed order of argument evaluation for func- 
tions whose calling sequence is different). 

• You should be familiar with the basic workings of the Zmacs editor. 

Note: these conversion commands are intended as an aid to conversion, not as a 
fully automatic conversion tool. Used properly, they will save you time and effort, 
but you must monitor the results carefully after each step and be aware that you 
might have to do some manual work after conversion. For instance, comments 
might not end up exactly in the right place in the rearranged program, indentation 
might change, converted functions might need some additions to the code, and so 
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on. Many CLIM functions support fewer options than their Dynamic Windows 
counterparts, so conversion often removes these options from the program or 
leaves them unconverted, which will cause a run-time error. Either way, you'll 
need to decide what you want the CLIM version of the program to do and adjust it 
accordingly. 

Getting Started 

Load the CLIM and Conversion Tools systems (in either order). 



Command 
Command 
Command 
Command 



Load System CLIM 

Load System GENERA-CLIM ;if you want the Genera port 

Load System POSTSCRIPT-CLIM ;if you want the PostScript port 

Load System Conversion Tools 



Note: The CLX port of CLIM is not currently a supported port of CLIM under 
Genera. It exists only as a sample port. 

Conversion Procedures 

1. Most Dynamic Windows programs are written in Symbolics Common Lisp. If 
yours is written in Zetalisp, first convert it to Symbolics Common Lisp using 
the Zetalisp to Common Lisp conversion tool ( see the section "Zetalisp to 
Common Lisp Conversion" ). 

2. Convert your program to a new package using either of these commands: 

m-X Convert Package of Buffer 
m-X Convert Package of Tag Table 

This step is optional, but it is useful because it allows you to run the Dynam- 
ic Windows and CLIM versions of the program side by side without them in- 
terfering with each other. When you test and fix the CLIM version, it's often 
useful to have the original Dynamic Windows version available for compari- 
son. 

If you plan to convert your program to a more portable dialect of Common 
Lisp, along with converting to CLIM, you should select a package in the 
CLtL, CLtL-Only, or Cloe package universe. 

3. Compile any macro definitions that your program uses. This step is optional, 
but helps the next step work better. Some conversions, for example of com- 
mand definitions, analyze the source code of your program and having all the 
macro definitions available results in more accurate analysis. 

4. Convert the Dynamic Windows functions to CLIM using either of these com- 
mands with the "DW to CLIM" conversion set: 
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m-X Convert Functions of Buffer 
m-X Convert Functions of Tag Table 

Read the queries carefully before answering them, and don't type ahead. It is 
often useful to accept conversions that are not quite correct; you will probably 
need to do some manual conversion afterwards anyway, so it may be useful to 
accept an automatic conversion that gets you closer to the goal (even if it 
may not be exactly what you want). 

5. Review the warnings printed during the conversion, check over the code by 
hand, and compile it. You can use c-n-Scroll to review the warnings printed 
in the typeout window. While checking over the code, you might want to fix 
up the indentation and formatting; some of the more complex conversions 
tend to mangle the indentation and line divisions, producing code that works 
but is difficult to read. 

6. Note that since a Dynamic Windows program-framework is a Flavors object, 
and a CLIM application frame is a CLOS object, you may need to run the Fla- 
vors to CLOS conversion tool before your CLIM program will compile. 

See the section "Flavors to CLOS Conversion". 

7. You might want to run the "Symbolics Common Lisp to Portable Common 
Lisp" and "Common Lisp to Common Lisp Developer" conversion tools at this 
time, especially if you selected a package universe other than Common Lisp in 
step 2. See the section "Symbolics Common Lisp to Portable Common Lisp 
Conversion". 

When you are satisfied with your CLIM program, and it compiles without errors or 
warnings, you can run it. 

For example, to run your CLIM program under Genera use climrdefine-genera- 
application and the Select Activity command. 

You can also use the following procedure: 

(setq xportx (cl im: find-port)) 

(setq xframex (cl im:make-appl i cation-frame ' your- frame-type : parent xportx)) 

(cl im : run-f rame-top-1 evel xframex) 



Summary of Differences Between CLIM 1.1 and CLIM 2.0 

CLIM 2.0 is a more robust product than CLIM 1.1. Many customer-requested fea- 
tures have been added, and many bugs have been fixed. 

However, the main reason for the existence of CLIM 2.0 is to provide integrated 
support for gadgets and event management so that CLIM applications can use 
many of the facilities found in standard toolkits. Some of the new features of 
CLIM 2.0 include the following: 
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• A new window and event management model that supports use of standard user 
interface toolkits when running on standard platforms, such as Motif under Alle- 
gro or Lucid Common Lisp. Since Genera does not support toolkits like Motif, 
CLIM 2.0 includes a set of gadgets, including scroll bars, push buttons, toggle 
buttons, radio and check boxes, pull-down menus, sliders, text editing panes, and 
list and option panes. 

• Integration between CLIM's gadgets and climraccepting-values. 

• A set of drawing functions that draw multiple graphics, for example, climrdraw- 
lines* and climrdraw-rectangles*. 

• CLIM 2.0 supports use of pixmaps, and has clim:with-output-to-pixmap and 
clim:copy-area functions. This can be used to cache portions of a display that 
needs to be rapidly, repeatedly drawn. 

• Functions to read Xll bitmap files and convert them to CLIM patterns, such as 
clim:make-pattern-from-bitmap-file. 

• Keyboard gestures are now specified in a more portable fashion. For example, 
what would have been #\control-X in CLIM 1.1 is now specified as (:x : con- 
trol). This allows greater portability, but it is an incompatible change from 
CLIM 1.1. 

• A new form for defining drag-and-drop translators, called clim:define-drag-and- 
drop-translator. 

• The completion presentation types now support rprinter and rhighlighter op- 
tions. 

• The input editor has a much richer set of editing commands. Type control-Help 
to see the entire set of commands. 

• The appearance of the mouse cursor can be changed, either directly by calling 
setf on climrpointer-cursor, or by changing the cursor associated with a CLIM 
sheet by calling setf on climrsheet-pointer-cursor. 

• Command tables may now inherit menu items from superior command tables. 

• The command processor now tells you what the defaults are for keyword argu- 
ments when you type Help while reading a command. 

• clim:surrounding-output-with-border now takes drawing options. 

• The graph formatter is now more sophisticated. 

• The new clim-sys package contains a number of generally useful utilities. 

• A number of new demos, including a "color chooser", a simple bitmap editor, a 
simple graphical editor, a Peek-like utility, a data plotting program, and a 
graphical browser. Note that these are demo programs; they are not intended to 
be of product quality, but are meant to be instructive in the use of CLIM 2.0. 
The CLIM Lisp Listener is particularly useful when you are debugging frag- 
ments of CLIM code; type Select Lambda (symbol -shift-L) in Genera to use it. 

Converting From CLIM 1.1 to CLIM 2.0 
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The CLIM 1.1 to CLIM 2.0 conversion tools are another set of commands like the 
Dynamic Windows to CLIM conversion tools. Like the Dynamic Windows to CLIM 
conversion tools, the CLIM 1.1 to CLIM 2.0 tools will not perform the conversion 
completely. You will need to perform additional editing of your CLIM 1.1 programs 
in order to generate working CLIM 2.0 programs. 

Again, these conversion commands are intended as an aid to conversion to CLIM 
2.0, not as a fully automatic conversion tool. Used properly, they will save you 
time and effort, but you must monitor the results carefully after each step and be 
aware that you might have to do some manual work after conversion. 

Note: these conversion tools are supported only in Genera. 

For more information on conversion tools in general, see the section "Conversion 
Tools" and see the section "Converting from Dynamic Windows to CLIM". 

Getting Started 

Load the CLIM and Conversion Tools systems (in either order). 

Load System CLIM 



Command 
Command 
Command 
Command 



Load System GENERA-CLIM ;if you want the Genera port 
Load System POSTSCRIPT-CLIM ;if you want the PostScript port 
Load System Conversion Tools 



Conversion Procedures 

1. Convert the CLIM 1.1 functions to CLIM 2.0 using either of these commands 
with the "CLIM 1.1 to CLIM 2.0" conversion set: 

m-X Convert Functions of Buffer 
m-X Convert Functions of Tag Table 

Read the queries carefully before answering them, and don't type ahead. It is 
often useful to accept conversions that are not quite correct; you will probably 
need to do some manual conversion afterwards anyway, so it may be useful to 
accept an automatic conversion that gets you closer to the goal (even if it 
may not be exactly what you want). 

2. Review the warnings printed during the conversion, check over the code by 
hand, and compile it. You can use c-n-Scroll to review the warnings printed 
in the typeout window. While checking over the code, you might want to fix 
up the indentation and formatting; some of the more complex conversions 
tend to mangle the indentation and line divisions, producing code that works 
but is difficult to read. 

3. The CLIM 1.1 to CLIM 2.0 conversion tools do not convert the rpanes and 
rlayouts options from clim:define-application-frame. You must do this your- 
self. 
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When you are satisfied with your CLIM 2.0 program, and it compiles without er- 
rors or warnings, you can run it. 

Here are some of the incompatible changes from CLIM 1.1 to CLIM 2.0. Most of 
these are picked up by the CLIM 1.1 to CLIM 2.0 conversion tools. 

The rpanes and rlayouts clauses to clim:define-application-frame are now com- 
pletely different. The conversion tools do not handle this, since it is not clear 
what should be done in many cases. 

clim:run-frame-top-level now takes keyword arguments. You must include &key 
in your methods for this function. 

clim:set-frame-layout has been removed in favor of using setf on climrframe- 
current-layout. 

clim:frame-top-level-window is now called clim:frame-top-level-sheet. 

clim:command-enabled-p is now called climrcommand-enabled. climrdisable- 
command and climrenable-command have been removed in favor of using setf 
on climrcommand-enabled. 

clim:open-root-window has been removed. Its closest replacement is climrfind- 
port, although you may find that you rarely need to explicitly specify a port. 

The rstream, robject, and :type keyword arguments to clim:with-output-as- 

presentation are now required arguments, since it was always necessary to sup- 
ply these arguments. 

clim:+background+ is now called clim:+background-ink+, and 
clim:+foreground+ is now called clim:+foreground-ink+. This was done to be 
consistent with clim:+flipping-ink+. 

clim:make-color-rgb is now called clim:make-rgb-color, and climrmake-color- 
ihs is now called clim:make-ihs-color. 

climrdraw-character, climrdraw-character*, climrdraw-string, and climrdraw- 
string* have all been removed in favor of using clim:draw-text and climrdraw- 
text*. 

clim:draw-icon and climrdraw-icon* are now called climrdraw-pattern*. 

The argument order to clim:with-text-style, clim:with-text-family, climrwith- 

text-face, and clim:with-text-size has been changed so that the stream argu- 
ment is first. 

climrstream-cursor-position* is now called climrstream-cursor-position, 
climrstream-set-cursor-position* is now called clim:stream-set-cursor-position, 
and climrstream-increment-cursor-position* is now called climrstream- 
increment-cursor-position. 

climrcursor-position* is now called climrcursor-position, and climrcursor-set- 
position* is now called clim:cursor-set-position. 

The argument order to clim:with-end-of-line-action and climrwith-end-of-page- 

action has been changed so that the stream argument is first. 

climrstream-pointer-position* is now called climrstream-pointer-position, and 
climrstream-set-pointer-position* is now called clim:stream-set-pointer- 
position. 
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climrpointer-position* is now called climrpointer-position, and climrpointer-set- 
position* is now called clim:pointer-set-position. 

climrevent-window is now called clim:event-sheet. 

clim:pointer-event-shift-mask is now called clim:event-modifier-state. 

The rinter-column-spacing, :inter-row-spacing, and rmultiple-columns-inter- 
column-spacing keyword arguments to clim:formatting-table have been re- 
named to :x-spacing, :y-spacing, and :multiple-columns-x-spacing. 

The :minimum-width and rminimum-height keyword arguments to 
clim:formatting-cell have been renamed to :min-width and :min-height. 

The rinter-column-spacing, :inter-row-spacing, and :no-initial-spacing keyword 
arguments to clim:formatting-item-list and climrformat-items have been re- 
named to :x-spacing, :y-spacing, and rinitial-spacing. 

The rinter-column-spacing and :inter-row-spacing keyword arguments to 
climrmenu-choose and clim:draw-standard-menu have been renamed to rx- 
spacing and :y-spacing. 

The :draw-p and :record-p keyword arguments to climrwith-output-recording- 
options have been renamed to :draw and rrecord. 

clim:*unsupplied-argument* is now called 

clim:*unsupplied-argument-marker*. 

The rinter-column-spacing and :inter-row-spacing keyword arguments to 
clim:display-command-table-menu has been renamed to :x-spacing and ry- 
spacing. 

The :test keyword argument has been removed from climradd-command-to- 
command-table, clim:add-keystroke-to-command-table, and climrremove- 
keystroke-from-command-table. 

The :keystroke-test keyword argument has been removed from climrread- 
command and clim:read-command-using-keystrokes. 

climrwindow-viewport-position* is now called climrwindow-viewport-position, 
and climrwindow-set-viewport-position* is now called climrwindow-set- 
viewport-position. 

clim:position-window-near-carefully is now called 

clim:position-sheet-carefully. 

clim:position-window-near-pointer is now called climrposition-sheet-near- 
pointer. 

clim:size-menu-appropriately is now called clim:size-frame-from-contents. 

clim:stream-draw-p is now called clim:stream-drawing-p, and climrstream- 
record-p is now called clim:stream-recording-p. 

climroutput-record-position* is now called climroutput-record-position, and 
clim:output-record-set-position* is now called clim:output-record-set-position. 

clim:output-record-element-count is now called clim:output-record-count. 

climroutput-record-elements is now called climroutput-record-children. 
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clim:output-record-refined-sensitivity-test is now called climroutput-record- 
refined-position-test. 

climroutput-recording-stream-output-record is now called climrstream-output- 
history. 

clim:output-recording-stream-current-output-record-stack is now called 
climrstream-current-output-record. 

climroutput-recording-stream-replay is now called climrstream-replay. 

climradd-output-record is now called clim:stream-add-output-record. 

climradd-output-record-element is now called climradd-output-record, and 
climrdelete-output-record-element is now called climrdelete-output-record. 

clim:map-over-output-record-elements is now called clim:map-over-output- 
records, clim:map-over-output-record-elements-containing-point* is now called 
clim:map-over-output-records-containing-position, and clim:map-over-output- 
record-elements-overlapping-region is now called clim:map-over-output- 
records-overlapping-region. 

climrdragging-output-record is now called climrdrag-output-record. 

The frame argument to climrfind-presentation-translators is now a command- 
table argument. 

The :shift-mask keyword argument to climrtest-presentation-translator, 
climrfind-applicable-translators, clim:presentation-matches-context-type, and 
climrfind-innermost-applicable-presentation is now a :modifier-state argument. 

clim:define-gesture-name uses a completely different syntax for specifying the 
gesture, and clim:add-pointer-gesture-name has been replace by climradd- 
gesture-name. 

clim:remove-pointer-gesture-name is now called clim:delete-gesture-name. 

clim:dialog-view is now called clim:textual-dialog-view, and clim:+dialog-view+ 
is now called clim:+textual-dialog-view+. 

clim:menu-view is now called clim:textual-menu-view, and clim:+menu-view+ 
is now called clim:+textual-menu-view+. 

climrcall-presentation-generic-function has been replaced by a pair of func- 
tions, climrapply-presentation-generic-function and climrfuncall-presentation- 
generic-function. 

The ractivation-characters, radditional-activation-characters, :blip-characters, 
and :additional-blip-characters to climraccept are now called ractivation- 
gestures, radditional-activation-gestures, rdelimiter-gestures, and radditional- 
delimiter-gestures. 

clim:*activation-characters* is now called clim:*activation-gestures*, and 
clim:*standard-activation-characters* is now called clim:*standard-activation- 
gestures*. 

clim:*blip-characters* is now called clim:*delimiter-gestures*. 

clim:activation-character-p is now called clim:activation-gesture-p, climrblip- 
character-p is now called clim:delimiter-gesture-p. 
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climrwith-activation-characters is now called climrwith-activation-gestures, 
and clim:with-blip-characters is now called climrwith-delimiter-gestures. 

clim:*abort-characters* is now called clim:*abort-gestures*. 

clim:*complete-characters* is now called clim:*completion-gestures*, 
clim:*help-characters* is now called clim:*help-gestures*, and 
clim:*possibilities-characters* is now called clim:*possibilities-gestures*. 

climrinput-position is now called clim:stream-scan-pointer, and climrinsertion- 
pointer is now called climrstream-insertion-pointer, and clim:rescanning-p is 
now called clim:stream-rescanning-p. 

The right and bottom arguments to climrwith-bounding-rectangle* are now re- 
quired. 

climrpoint-position* is now called climrpoint-position. 

climrregion-contains-point*-p is now called clim:region-contains-position-p. 

climrbounding-rectangle-position* is now called climrbounding-rectangle- 
position, and climrbounding-rectangle-set-position* is now called 
clim:bounding-rectangle-set-position. 

The argument order to clim:make-3-point-transformation and climrmake-3- 
point-transformation* has been changed. 

climrcompose-rotation-transformation is now called climrcompose-rotation- 
with-transformation, climrcompose-scaling-transformation is now called 
clim:compose-scaling-with-transformation, and climrcompose-translation- 
transformation is now called clim:compose-translation-with-transformation. 

climrtransform-point* is now called climrtransform-position, and 
climruntransform-point* is now called climruntransform-position. 



Using the CLIM Demos 

The CLIM Demo system provides a number of examples of small and medium-sized 
applications that use CLIM. They all run as part of a demo loop that uses a CLIM 
menu to let you choose which demo to run. The source files for the CLIM demos 
in included in SYS :CLIM;REL-2; DEMO;*. LISP. You may find that reading the source 
code for the CLIM demos will provide many useful hints and techniques for writ- 
ing your own CLIM applications. 

This section describes how to run the CLIM demos. 

To run the demos: 

• Ensure that the CLIM system is loaded, plus an appropriate back-end (such as 
Genera-CLIM). Then load the system CLIM-DEMOS. 

• To run the demos, evaluate the form (clim-demo:start-demo). If you are run- 
ning Genera, you can also use the : Demonstrate CLIM command. This will pop up 
a menu of the demos to run. 



Page 1236 



If you are using Genera, you may also want to try the CLIM demos using the 
"gadget menu bar" style of frame manager. You can do this by evaluating the fol- 
lowing: 

(cl im-demo: start-demo 

:framem (cl im: find-frame-manager : gadget-menu-bar t)) 

The following sections describe the operation of each of the demos. 

The CLIM Lisp Listener 

This is a simple Lisp Listener (in SYS :CLIM;REL-2; DEMO; LISTENER. LISP). It includes 
a basic Lisp read-eval-print loop to which you can type either Lisp forms or CLIM 
commands. It includes a mouse documentation line and provides a scrollable histo- 
ry. The available commands include Show Directory, Show File, Compile File, Load 
File, and so forth. You may find the CLIM Lisp Listener very useful when debug- 
ging small CLIM programs. 

Some of the techniques used in the CLIM Lisp Listener include: 

• Use of a custom top-level loop that reads both commands and Lisp forms, and 
uses keystroke accelerators. 

• Use of patterns as a prompt. 

• Use of some interesting presentation translators. 

Note that, by default, *debug-io* is not rebound to the CLIM Lisp Listener win- 
dow, so any error needs to be dealt with in some other window. 

You can use the Quit command to exit from the CLIM Lisp Listener back to the 
demo menu. Under Genera, you can use Select A, (that is, lambda or symbol - 
shift-L) to create a CLIM Lisp Listener that runs in its own process. 

The Graphics Demo 

This is a simple application (in SYS :CLIM;REL-2; DEMO; GRAPHICS-DEMOS. LISP) that 
demonstrates some of the graphics facilities in CLIM. This demo uses color, which 
appears as stipple patterns on a monochrome system. It also uses transformations. 

The CAD Demo 

This demo is a very simple CAD system (in SYS :CLIM;REL-2; DEMO; CAD-DEMO. LISP) 
that lets you build up logic circuits using "and" and "or" gates. When you run it, 
click on the [Setup] command menu button, and it will display an example circuit. 
You can select gates or gate nodes with the mouse; look at the mouse documenta- 
tion line to see what operations are available. You can also create new components 
and connect them together. 

Some of the techniques used in the CAD Demo include: 

• Use of a custom output records that implement the logic components. 
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• Use of custom highlighting. 

• Use of a purely menu-driven command interaction style. 

• Use of climrdrag-output-record. 

Note: feedback circuits will cause the CAD demo program to crash. 

The Flight Planning Demo 

This example (in SYS :CLIM;REL-2; DEMO ;NAVFUN. LISP) sets up an application frame 
with a map of most of the airports in eastern Massachusetts. The airports and vi- 
sual references are selectable for various activities such as querying distance be- 
tween airports and building up a flight plan. This application demonstrates the 
power of inheritance of presentation types for accepting objects. 

Some of the techniques used in the Flight Planner include: 

• Use of a number presentation types, using specialization and inheritance to con- 
trol user interface behavior. 

• Use of custom highlighting. 

• Use of dialogs. 

• Use of table formatting. 

The 15 Puzzle 

This example (in SYS :CLIM;REL-2; DEMO; PUZZLE. LISP) is an implementation of the 15 
puzzle described in the CLIM Tutorial. 

The 15 Puzzle uses a simple direct-manipulation interaction style, and uses incre- 
mental redisplay in conjunction with table formatting. 

The Address Book Demo 

This example (in SYS :CLIM;REL-2; DEMO; ADDRESS-BOOK. LISP) is an implementation of 
a simple address book. You can look up, add, or remove addresses, and edit exist- 
ing entries. 

The Thinkadot Demo 

This example (in SYS :CLIM;REL-2; DEMO; THINKADOT. LISP) is an implementation of the 
mechanical "Thinkadot" game. 

The Plotting Demo 

This example (in SYS :CLIM;REL-2; DEMO; PLOT. LISP) is a simple data plotting applica- 
tion. There are a number of interesting techniques used in the application: 

• Using climrtracking-pointer to select a region on a window, including modifica- 
tion of the pointer cursor. 

• Sophisticated use of formatted output facilities. 
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• Use of a modeless dialog pane. 

• Use of a presentation action to implement "drag scrolling". 

The Color Chooser 

This example (in SYS:CLIM;REL-2;DEM0;C0L0R-EDIT0R.LISP) uses slider gadgets to 
implement a color chooser. You can drag a slider in either the RGB or IHS panes 
to change the color of the color swatch. The main techniques used in this program 
are: 

• A custom pane to implement the color swatch. 

• An "exit" push button. 

• Two sets of "linked" sliders that track each other. 

The Boxes-and- Wires Editor 

The boxes-and-wires editor (in SYS:CLIM;REL-2;DEM0;GRAPHICS-EDIT0R.LISP) is a pro- 
gram that allows you to create diagrams consisting of boxes optionally connected 
by wires. As you drag a box around, the wires track the boxes. You can also select 
a box and perform some operations on the selected box. 

The interesting techniques in the program are: 

• Use of incremental redisplay and "redisplay ticks" that control when redisplay 
should occur. 

• Use of climrtracking-pointer. 

• Use of CLIM's bounding rectangle functions. 

• Use of multiple command tables to group related commands. 

• Use of a presentation type with a graphical interface to represent line thickness 
and style. 

The Bitmap Editor 

The bitmap editor (in SYS:CLIM;REL-2;DEM0;BITMAP-EDIT0R.LISP) allows you to cre- 
ate a little "bitmap" (actually, a CLIM pattern). The main interesting thing in 
this program is the way the grid is built up, the way cells in the grid are modi- 
fied, and how the grid is connected to the display of the pattern represented by 
the grid pane. 

The Icosahedron Demo 

The file SYS: CLIM; REL-2; DEMO; I CO. LISP implements the traditional "Ico" demo that 
can be found on almost everywhere. You can "throw" or "catch" an icosahedral 
"ball", which bounces around the display pane. 
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The CLIM Browser 

The CLIM Browser (in SYS :CLIM;REL-2; DEMO; BROWSER. LISP) implements an extensi- 
ble, graphical browser. To use it, first select the type of thing you want to browse 
(classes, packages, or whatever), then the primary "axis" along which you want 
browse (subclasses, superclasses, or whatever). Then use the Show Graph command 
to get an initial display. Once there is an initial display, you can click on nodes in 
the graph to add, remove, or hide nodes, "ellipsize" a node, or expand an ellipsis. 
You can also get a hardcopy of a graph. 

The interesting techniques in this program are: 

• Sophisticated use of incremental redisplay in conjunction with graph formatting, 
and use of "redisplay ticks" that control when redisplay should occur. 

• Use of multiple command tables to group related commands. 

The "Peek" Demo 

The "Peek" Demo (in SYS :CLIM;REL-2; DEMO; PEEK-FRAME. LISP) is a small process sta- 
tus program. It demonstrates another way to use incremental redisplay. 

The Custom Output Records Demo 

The Customer Output Records Demo (in SYS :CLIM;REL-2; DEMO; CUSTOM-RECORDS. LISP) 
shows the benefit of using special-purpose output records when you can take ad- 
vantage of detailed knowledge of your application's data. This program displays the 
same data set three different ways. The simplest (and slowest) way simply creates 
a new presentation for each point in the data set and display that. A somewhat 
better technique is to use each data point as its own presentation; this is possible 
because each point already has knowledge about where is will be displayed. The 
best technique (at least for this application) is to create a "container" output 
record that holds all of the data points, and then display that. For this application, 
the third technique is about three times faster than the first. 



Drawing Graphics in CLIM 

Concepts of Drawing Graphics in CLIM 

Drawing Functions and Options 

CLIM offers a set of drawing functions for drawing points, lines, polygons, rectan- 
gles, ellipses, circles, and text. You can affect the way the geometric objects are 
drawn by supplying drawing options to the drawing functions. The drawing options 
support clipping, transformation, line style, text style, ink, and other aspects of the 
graphic to be drawn (see the section "Using CLIM Drawing Options"). 

In many cases, it is convenient to use climrwith-drawing-options to surround sev- 
eral calls to drawing functions, each using the same options. You can override one 
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or more drawing options in any given call by supplying keywords to the drawing 
functions themselves. Using climrwith-drawing-options around several drawing 
functions that would otherwise use the same options is also more efficient than 
supplying the drawing options separately to each drawing function. 

The Drawing Plane 

When drawing graphics in CLIM, you imagine that they appear on a drawing 
plane. The drawing plane extends infinitely in four directions and has infinite reso- 
lution (no pixels). A line that you draw on the drawing plane is infinitely thin. The 
drawing plane provides an idealized version of the graphics you draw; it has no 
material existence and cannot be viewed directly. 

Of course, you intend that the graphics should be visible to the user, and must be 
presented on a real display device. CLIM transfers the graphics from the drawing 
plane to the display device via the rendering process. Because the display device is 
hardware that has physical constraints, the rendering process is forced to compro- 
mise when it draws the graphics on the device. The actual visual appearance on 
the display device is only an approximation of the idealized drawing plane. 

Figure 38 shows the conceptual model of the drawing functions sending graphical 
output to the drawing plane, and the graphics being transferred to a screen by 
rendering. 

rendering 



Drawing 
Functions 




Screen 



Drawing 
Plane 



Figure 59. Rendering from Drawing Plane to Window 

The distinction between the idealized drawing plane and the real window enables 
you to develop programs without considering the constraints of a real window or 
other specific output device. This distinction makes CLIM's drawing model highly 
portable. 

CLIM application programs can inquire about the constraints of a device, such as 
its resolution and other characteristics, and modify the desired visual appearance 
on that basis. This practice trades portability for a finer degree of control of the 
appearance on a given device. (Note: Currently, this feature is not fully imple- 
mented.) 
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Coordinates 

When producing graphic output on the drawing plane, you indicate where to place 
the output with coordinates. Coordinates are a pair of numbers that specify the X 
and Y placement of a point. When a window is first created, the origin (that is, 
x=0, y=0) of the drawing plane is positioned at the top-left corner of the window. 
Figure 39 shows the orientation of the drawing plane, X extends toward the right, 
and Y extends downward. 



Figure 60. X and Y Axes of Drawing Plane 

As the window scrolls downward, the origin of the drawing plane moves above the 
top edge of the window. Because windows maintain an output history, the Y-axis 
can extend to a great length. In many cases, it is burdensome to keep track of the 
coordinates of the drawing plane, and it can be easier to think in terms of a local 
coordinate system. 

For example, you might want to draw some business graphics as shown in Figure 
40. For these graphics, it is more natural to think in terms of the Y-axis growing 
upwards, and to have an origin other than the origin of the drawing plane, which 
might be very far from where you want the graphics to appear. You can create a 
local coordinate system in which to produce your graphics. The way you do this is 
to define a transformation which informs CLIM how to map from the local coordi- 
nate system to the coordinates of the drawing plane. For more information, see 
clim:with-room-for-graphics. 
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Figure 61. Using a Local Coordinate System 



Sheets and Streams, and Mediums 

A sheet is the most basic window-like object supported by CLIM. It has two prima- 
ry properties: a region, and a transformation that relates its coordinate system to 
the coordinate system of its parent. A stream is a special kind of sheet that imple- 
ments the stream protocol; streams include additional state such as the current 
text cursor position (which is some point in the drawing plane). 

A medium is an object on which drawing takes place. A medium has as attributes: 
a drawing plane, the medium's foreground and background, a drawing ink, a 
transformation, a clipping region, a line style, a text style, and a default text style. 
Sheets and streams that support output have a medium as one of their attributes. 

The drawing functions take a medium argument that specifies the destination for 
output. The drawing functions are specified to be called on mediums, but they can 
be called on most sheets and streams as well. 

The medium keeps track of default drawing options, so if drawing functions are 
called and some options are unspecified, they default to the values maintained by 
the medium. 

Different medium classes are provided to allow users to draw on different sorts of 
devices, such as displays and printers. 



Examples of Using CLIM Drawing Functions 

Figure 41 shows the result of evaluating the following forms: 

(cl im: draw-rectangle* xmy-windowx 10 10 200 150 

: filled nil : 1 ine-thickness 2) 
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(cl im:draw-l inex xmy-windowx 200 10 10 150) 

(cl im:draw-pointx xmy-windowx 180 25) 

(cl im:draw-ci rclex xmy-windowx 100 75 40 :filled nil) 

(cl im:draw-ell ipsex xmy-windowx 160 110 30 10 :filled nil) 

(cl im:draw-el 1 ipsex xmy-windowx 160 110 10 30) 

(cl im:draw-polygonx xmy-windowx '(20 20 50 80 40 20) :filled nil) 

(cl im:draw-polygonx xmy-windowx '(30 90 40 110 20 110)) 




Figure 62. Simple Use of the Drawing Functions 



CLIM Drawing Functions 

Most of CLIM's drawing functions come in pairs. One function takes two argu- 
ments to specify a point by its X and Y coordinates; the corresponding function 
takes one argument, a point object. The function accepting a point object has a 
name without an asterisk (*), and the function accepting coordinates of the point 
has the same name with an asterisk appended to it. For example, clim:draw-point 
accepts a point object, and clim:draw-point* accepts coordinates of a point. We ex- 
pect that using the functions that take spread point arguments and specifying 
points by their coordinates will be more convenient in most cases. ( If you prefer 
to create and use point objects, see the section "CLIM Point Objects"). 

The drawing functions take keyword arguments specifying drawing options. For in- 
formation on the drawing options, see the section "Using CLIM Drawing Options". 

The following drawing functions operate on either either mediums, or sheets and 
streams. When called on an output recording stream that has output recording en- 
abled, these functions all record their output. 
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clim:draw-point medium point &key -.line-style :line-thickness :line-unit sink .-clip- 
ping-region .-transformation 
Draws a point on medium at the position indicated by point. 

clim:draw-point* medium x y &key -.line-style :line-thickness -.line-unit sink .-clip- 
ping-region .-transformation 
Draws a point on medium at the position indicated by x and y. 

climrdraw-points medium point-seq &key -.line-style :line-thickness -.line-unit sink 
.-clipping-region .-transformation 

Draws a set of points on medium, point-seq is a sequence of point objects 
specifying where a point is to be drawn. 

climrdraw-points* medium coord-seq &key -.line-style :line-thickness -.line-unit sink 
.-clipping-region .-transformation 

Draws a set of points on medium, coord-seq is a sequence of pairs of X/Y 
pairs. Each pair specifies a point to be drawn. 

clim:draw-line medium point-1 point-2 &key -.line-style :line-thickness -.line-unit -.line- 
dashes :line-cap-shape sink .-clipping-region .-transformation 
Draws a line segment on medium. The line starts at the position speci- 
fied by point-1 and ends at the position specified by point-2, two point 
objects. 

clim:draw-line* medium xl yl x2 y2 &key -.line-style :line-thickness -.line-unit -.line- 
dashes :line-cap-shape sink .-clipping-region .-transformation 
Draws a line segment on medium. The line starts at the position speci- 
fied by (xl, yl), and ends at the position specified by (x2, y2). 

clim:draw-lines medium point-seq &key -.line-style :line-thickness -.line-unit -.line- 
dashes :line-cap-shape sink .-clipping-region .-transformation 
Draws a set of disconnected line segments onto medium, point-seq is a 
sequence of pairs of points. Each point pair specifies the starting and 
ending point of a line. 

climrdraw-lines* medium coord-seq &key -.line-style :line-thickness -.line-unit -.line- 
dashes :line-cap-shape sink .-clipping-region .-transformation 
Draws a set of disconnected line segments onto medium, coord-seq is a 
sequence of pairs of X and Y positions. Each pair of XY pairs specifies 
the starting and ending point of a line. 

clim:draw-arrow medium start-point end-point &key :from-head (:to-head t) (.-head- 
length 10) (-.head-width 5) .-line-style :line-thickness -.line-unit :line-dashes 
:line-cap-shape sink .-clipping-region .-transformation 

Draws an arrow on medium. The arrow starts at the position specified 
by start-point and ends with the arrowhead at the position specified by 
end-point, two point objects. 

climrdraw-arrow* medium xl yl x2 y2 &key :from-head (:to-head t) (-head-length 
10) (:head-width 5) .-line-style :line-thickness -.line-unit :line-dashes :line- 
cap-shape sink .-clipping-region .-transformation 
Draws an arrow on medium. The arrow starts at the position specified 
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by (xl,yl) and ends with the arrowhead at the position specified by 

(x2,y2). 

climrdraw-polygon medium point-seq &key (.-closed t) (.-filled t) .-line-style .-line- 
thickness -.line-unit :line-dashes :line-joint-shape :line-cap-shape sink .-clip- 
ping-region .-transformation 

Draws a polygon, or sequence of connected lines, on medium. The key- 
word arguments control whether the polygon is closed (each segment is 
connected to two other segments) and filled, point-seq is a sequence of 
points that indicate the start of a new line segment. 

climrdraw-polygon* medium coord-seq &key (-closed t) (-filled t) .-line-style .-line- 
thickness -.line-unit :line-dashes :line-joint-shape :line-cap-shape sink .-clip- 
ping-region .-transformation 

Draws a polygon, or sequence of connected lines, on medium. The key- 
word arguments control whether the polygon is closed (each segment is 
connected to two other segments) and filled, coord-seq is a sequence of 
alternating X and Y positions that indicate the start of a new line seg- 
ment. 

climrdraw-rectangle medium pointl point2 &rest args &key -.line-style -.line- 
thickness -.line-unit :line-dashes :line-joint-shape sink .-clipping-region 
.-transformation (-filled t) 

Draws an axis-aligned rectangle on medium. The boundaries of the rect- 
angle are specified by the two points pointl and point2. 

climrdraw-rectangle* medium xl yl x2 y2 &key (-filled t) .-line-style :line-thickness 
-.line-unit :line-dashes :line-joint-shape sink .-clipping-region .-transformation 

Draws an axis-aligned rectangle on medium. The boundaries of the rect- 
angle are specified by xl, yl, x2, and y2. 

climrdraw-rectangles medium point-seq &rest args &key -.line-style :line-thickness 
-.line-unit :line-dashes :line-joint-shape sink .-clipping-region .-transformation 
(■filled t) 

Draws a set of axis-aligned rectangles on medium, point-seq is a se- 
quence of pairs of points. 

climrdraw-rectangles* medium coord-seq &rest args &key -.line-style :line-thickness 
-.line-unit :line-dashes :line-joint-shape sink .-clipping-region .-transformation 
(■filled t) 

Draws a set of axis-aligned rectangles on medium, coord-seq is a se- 
quence of 4-tuples xl, yl, x2, and y2, with (xl,yl) at the upper left and 
(x2,y2) at the lower right in the standard +Y-downward coordinate sys- 
tem. 

climrdraw-ellipse medium point radius-1-dx radius-1-dy radius-2-dx radius-2-dy 
&key .start-angle -.end-angle (-.filled t) .-line-style :line-thickness -.line-unit 
:line-dashes :line-cap-shape sink .-clipping-region .-transformation 
Draws an ellipse or elliptical arc on medium. The center of the ellipse is 
specified by point. 
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climrdraw-ellipse* medium center-x center-y radius-1-dx radius-1-dy radius-2-dx ra- 
dius-2-dy &key .start-angle :end-angle (.-filled t) .-line-style :line-thickness 
:line-unit :line-dashes :line-cap-shape sink .-clipping-region .-transformation 
Draws an ellipse or elliptical arc on medium. The center of the ellipse is 
specified by center-x and center-y. 

climrdraw-circle medium center radius &key .start-angle -.end-angle (-.filled t) .-line- 
style :line-thickness -.line-unit :line-dashes :line-cap-shape sink .-clipping- 
region .-transformation 

Draws a circle or arc on medium. The center of the circle is specified by 
center, and the radius is specified by radius. 

climrdraw-circle* medium center-x center-y radius &key .start-angle -.end-angle 
(-.filled t) -.line-style :line-thickness -.line-unit :line-dashes :line-cap-shape 
sink .-clipping-region .-transformation 

Draws a circle or arc on medium. The center of the circle is specified by 
center-x and center-y, and the radius is specified by radius. 

clim:draw-oval medium point x-radius y-radius &key (-filled t) .-line-style .-line- 
thickness -.line-unit :line-dashes :line-cap-shape sink .-clipping-region .-trans- 
formation 

Draws an oval, that is, a "race-track" shape, centered on point, a point 
object, with the specified X and Y radii. 

clim:draw-oval* medium center-x center-y x-radius y-radius &key (-filled t) .-line- 
style :line-thickness -.line-unit :line-dashes :line-cap-shape sink .-clipping- 
region .-transformation 

Draws an oval, that is, a "race-track" shape, centered on (center-x 
center-y), with the specified X and Y radii. 

clim:draw-text medium text point &key (start 0) send (:align-x rleft) (:align-y 
rbaseline) :towards-point -.text-style -.text-family -.text-face -.text-size sink .-clip- 
ping-region .-transformation 

Draws text onto medium starting at the position specified by point, text 
can be either a character or a string. 

clim:draw-text* medium text x y &key (start 0) send (:align-x rleft) (:align-y 
rbaseline) :towards-x :towards-y -.text-style -.text-family -.text-face -.text-size 
-.ink -.clipping-region -.transformation 

Draws text onto medium starting at the position specified by x and y. text 
can be either a character or a string. 

climrdraw-design design stream &key sink .-clipping-region .-transformation -.line-style 
-.unit .-thickness -.joint-shape xap-shape .-dashes .-text-style .-text-family .-text- 
face -.text-size 
Draws design onto medium. 

climrdraw-pattern* stream pattern x y &key -.clipping-region -.transformation 
Draws the pattern pattern on stream at the position (x,y). 

climrdraw-pixmap medium pixmap point &rest args &key sink .-clipping-region 
.-transformation (-function boole-lj 
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Draws the pixmap pixmap on medium at the position point, creating a 
"pixmap output record" if medium is an output recording stream, .-func- 
tion is a boolean operation that controls how the source and destination 
bits are combined. 

climrdraw-pixmap* medium pixmap x y &rest args &key sink .-clipping-region 
.-transformation (.-function boole-lj 

Draws the pixmap pixmap on medium at the position (x,y), creating a 
"pixmap output record" if medium is an output recording stream, .-func- 
tion is a boolean operation that controls how the source and destination 
bits are combined. 

CLIM also provides some drawing functions that operate only on mediums. These 
functions take no drawing options directly, but instead use the drawing state in 
the medium. You may want to use these functions when you need higher perfor- 
mance than the ordinary drawing functions provide, but they are somewhat less 
convenient and do not support output recording. 

clim:medium-draw-point* medium x y 

Draws a point on the medium medium. The point is drawn at (x,y), 
transformed by the medium's current transformation. 

clim:medium-draw-points* medium position-seq 

Draws a set of points on the medium medium, position-seq is a sequence 
of coordinate pairs, which are real numbers. The coordinates in position- 
seq are transformed by the medium's current transformation. 

clim:medium-draw-line* medium xl yl x2 y2 

Draws a line on the medium medium. The line is drawn from (xl,yl) to 
(x2,y2), with the start and end positions transformed by the medium's 
current transformation. 

clim:medium-draw-lines* medium position-seq 

Draws a set of disconnected lines on the medium medium, position-seq is 
a sequence of coordinate pairs, which are real numbers. The coordinates 
in position-seq are transformed by the medium's current transformation. 

clim:medium-draw-polygon* medium position-seq closed filled 

Draws a polygon or polyline on the medium medium, position-seq is a se- 
quence of coordinate pairs, which are real numbers. The coordinates in 
position-seq are transformed by the medium's current transformation. 

clim:medium-draw-rectangle* medium xl yl x2 y2 filled 

Draws a rectangle on the medium medium. The corners of the rectangle 
are at (xl,yl) and (x2,y2), with the corner positions transformed by the 
medium's current transformation. If filled is t, the rectangle is filled, 
otherwise it is not. 

clim:medium-draw-rectangles* medium position-seq filled 

Draws a set of rectangles on the medium medium, position-seq is a se- 
quence of coordinate pairs, which are real numbers. The coordinates in 
position-seq are transformed by the medium's current transformation. If 
filled is t, the rectangles are filled, otherwise they are not. 



Page 1248 



clim:medium-draw-ellipse* medium center-x center-y radius-1-dx radius-1-dy radius- 
2-dx radius-2-dy start-angle end-angle filled 

Draws an ellipse on the medium medium. The center of the ellipse is at 
(x,y), and the radii are specified by the two vectors (radius- l-dx,radius-l- 
dy) and (radius-2-dx,radius-2-dy). The center point and radii are trans- 
formed by the medium's current transformation. 

clim:medium-draw-text* medium string-or-char x y start end align-x align-y to- 
wards-x towards-y transform-glyphs 

Draws a character or a string on the medium medium. The text is 
drawn starting at (x,y), and towards (toward-x,toward-y); these positions 
are transformed by the medium's current transformation. 

If you need even higher performance, you can draw directly on the underlying host 
window system object, but using this technique sacrifices portability. The following 
functions provide the necessary low-level access to the components of the medium 
and its owning sheet. 

clim:with-medium-state-cached (medium) &body body 

Declares that all of the drawing operations within body will use exactly 
the same drawing options. This allows CLIM back-ends to cache the 
state of the medium so that the medium does not need to be "decoded" 
for each drawing operation. 

clim:medium-sheet medium 

Returns the sheet with which the medium medium is associated. 

climrmedium-drawable medium 

Returns the host window system object (or "drawable") that is drawn on 
by the CLIM drawing functions when they are called on medium. 

climrsheet-device-region sheet 

Returns a region object that describes the region that sheet occupies on 
the display device. The coordinates are in the host's native window coor- 
dinate system. 

climrsheet-device-transformation sheet 

Returns a transformation that converts coordinates in sheet's, coordinate 
system into native coordinates on the display device. 

For example, the following code might be used by a CLX-based port of CLIM to 
draw lines (where convert-to-device-coordinates transforms and "fixes" its coor- 
dinates, and decode-ink-and-region "decodes" the ink and region into a X Win- 
dows gcontext). 
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(defmethod medium-draw-line* ((medium clx-medium) x1 y1 x2 y2) 
(let* ((sheet (cl im:medium-sheet medium)) 

(transform (cl im:sheet-device-transformation sheet)) 
(region (cl im:sheet-device-region sheet)) 
(ink (cl im:medium-ink medium)) 
(line-style (cl im:medium-l ine-style medium)) 
(drawable (cl im:medium-drawable medium))) 
(convert-to-device-coordinates transform x1 y1 x2 y2) 
(xl ib:draw-l ine drawable 

(decode-ink-and-region ink region) 
x1 y1 x2 y2))) 



General Geometric Objects in CLIM 



Regions in CLIM 

A region is an object that denotes a set of points in the plane. Regions include 
their boundaries; that is, they are closed. Regions have infinite resolution. 

A bounded region is a region that contains at least one point and for which there 
exists a number, d, called the region's diameter, such that if pi and p2 are points 
in the region, the distance between pi and p2 is always less than or equal to d. 

An unbounded region either contains no points or contains points that are arbitrar- 
ily far apart. 

Another way to describe a region is that it maps every (x,y) pair into either true 
or false (meaning member or not a member, respectively, of the region). 

The following classes are what CLIM uses to classify the various types of regions. 
All regions are a subclass of region, and all bounded regions are also a subclass of 
either climrpoint, climrpath, or climrarea. 

climrregion 

The protocol class that corresponds to a set of points. 

climrpoint 

The protocol class that corresponds to a mathematical point. 

climrpath 

This is a subclass of climrregion that denotes regions that have dimen- 
sionality 1. If you want to create a new class that obeys the path proto- 
col, it must be a subclass of climrpath. 

climrarea 

This is a subclass of climrregion that denotes regions that have dimen- 
sionality 2 (that is, have area). If you want to create a new class that 
obeys the area protocol, it must be a subclass of climrarea. 
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These two constants represent the regions that correspond, respectively, to all of 
the points on the drawing plane and none of the points on the drawing plane. 

clim:+everywhere+ 

The region that includes all the points on the infinite drawing plane. 

clim:+nowhere+ 

The empty region (the opposite of clim:+everywhere+). 



Region Predicates in CLIM 

The following functions can be used to examine certain aspects of regions, such as 
whether two regions are equal or if they overlap. 

clim:region-equal regionl region2 

Returns t if regionl and region2 contain exactly the same set of points, 
otherwise returns nil. 

clim:region-contains-region-p regionl region2 

Returns t if all points in region2 are members of regionl, otherwise re- 
turns nil. 

clim:region-contains-position-p region x y 

Returns t if the point (x,y) is contained in region, otherwise returns nil. 
This is a special case of clim:region-contains-region-p. 

clim:region-intersects-region-p regionl region2 

Returns nil if climrregion-intersection of the two regions would be 
clim:+nowhere+, otherwise returns t. 



Composition of CLIM Regions 

Region composition in CLIM is the process in which two regions are combined in 
some way (such as union or intersection) to produce a third region. 

Since all regions in CLIM are closed, region composition is not always equivalent 
to simple set operations. Instead, composition attempts to return an object that has 
the same dimensionality as one of its arguments. If this is not possible, then the 
result is defined to be an empty region, which is canonicalized to clim:+nowhere+. 
(For instance, the intersection of two lines that cross each other at a point is 
empty.) The exact details of this are specified with each function. 

Sometimes, composition of regions can produce a result that is not a simple con- 
tiguous region. For example, clim:region-union of two rectangular regions might 
not be rectangular. In order to support cases like this, CLIM has the concept of a 
region set, which is an object that represents one or more region objects related by 
some region operation, usually a union. 

clim:region-union regionl region2 

Returns a region that contains all points that are in either regionl or 
region2 (possibly with some points removed to satisfy the dimensionality 
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rule). The result of clim:region-union always has dimensionality that is 
the maximum dimensionality of regionl and region2. 

climrregion-intersection regionl region2 

Returns a region that contains all points that are in both regionl and 
region2 (possibly with some points removed to satisfy the dimensionality 
rule). The result of climrregion-intersection has dimensionality that is 
the minimum dimensionality of regionl and region2, or is 
clim:+nowhere+. 

climrregion-difference regionl region2 

Returns a region that contains all points in regionl that are not in re- 
gion2 (plus additional boundary points to make the result closed). The re- 
sult of climrregion-difference has the same dimensionality as regionl, or 
is clim:+nowhere+. 

clim:region-set 

The class that represents region sets; a subclass of region. 

clim:region-set-function region 

Returns a symbol representing the operation that relates the regions in 
region. This will be one of the symbols union, intersection, or set- 
difference. 

clim:region-set-regions region &key .-normalize 

Returns a sequence of the regions in region. Region can be either a re- 
gion-set or any member of region, in which case the result is simply a 
sequence of one element: region. 

clim:map-over-region-set-regions function region &key .-normalize 

Call function on each region in region. This is often more efficient than 
calling clim:region-set-regions. 



CLIM Point Objects 

A point is a mathematical point in the drawing plane, which is identified by its 
coordinates, a pair of real numbers. Points have neither area nor length. Note that 
a point is not the same thing as a pixel; CLIM's model of the drawing plane has 
continuous coordinates. 

You can create point objects and use them as arguments to the drawing functions. 
Alternatively, you can use the spread versions of the drawing functions, that is the 
drawing functions with stars appended to their names. For example, instead of 
clim:draw-point use climrdraw-point*, which takes two arguments that specify 
the point by its coordinates. (We generally recommend the use of the spread ver- 
sions.) 

The operations for creating and dealing with points are: 

climrpoint 

The protocol class that corresponds to a mathematical point. 
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clim:standard-point 

The standard class CLIM uses to implement points. This is the class 
that clim:make-point instantiates. 

clim:make-point x y 

Creates and returns a point object whose coordinates are x and y. 

climrpoint-position point 

Returns two values, the X and Y coordinates of point. 

clim:point-x point 

Returns the X coordinate of point. 

clim:point-y point 

Returns the Y coordinate of point. 



Other Region Types in CLIM 

The other types of regions are polylines, polygons, elliptical arcs, and ellipses. All 
of these region types are closed under affine transformations. 



Polygons and Polylines in CLIM 

A polyline is a path that consists of one or more line segments joined consecutively 
at their end-points. A line is a polyline that has only a single segment. 

Polylines that have the end-point of their last line segment coincident with the 
start-point of their first line segment are called closed; you should not confuse this 
use of the term "closed" with "closed" sets of points. 

A polygon is an area bounded by a closed polyline. 

If the boundary of a polygon intersects itself, the odd-even winding-rule defines the 
polygon: a point is inside the polygon if a ray from the point to infinity crosses the 
boundary an odd number of times. 

The classes that correspond to polylines and polygons are: 

climrpolyline 

The protocol class that corresponds to a polyline. This is a subclass of 
climrpath. 

climrpolygon 

The protocol class that corresponds to a mathematical polygon. This is a 
subclass of climrarea. 

climrstandard-polyline 

The standard class CLIM uses to implement polylines. This is a subclass 
of climrpolyline. This is the class that climrmake-polyline and 
climrmake-polyline* instantiate. 

climrstandard-polygon 

The standard class CLIM uses to implement polygons. This is a subclass 



Page 1253 



of climrpolygon. This is the class that climrmake-polygon and 
climrmake-polygon* instantiate. 



Constructors for CLIM Polygons and Polylines 

The following functions can be used to create polylines and polygons: 

climrmake-polygon point-seq 

Makes an object of class climrstandard-polygon consisting of the area 
contained in the boundary that is specified by the segments connecting 
each of the points in point-seq. 

climrmake-polygon* coord-seq 

Makes an object of class climrstandard-polygon consisting of the area 
contained in the boundary that is specified by the segments connecting 
each of the points represented by the coordinate pairs in coord-seq. 

climrmake-polyline point-seq &key .-closed 

Makes an object of class climrstandard-polyline consisting of the seg- 
ments connecting each of the points in point-seq. 

climrmake-polyline* coord-seq &key .-closed 

Makes an object of class climrstandard-polyline consisting of the seg- 
ments connecting each of the points represented by the coordinate pairs 
in coord-seq. 



Accessors for CLIM Polygons and Polylines 

The following functions can be used to access the components of polygons and 
polylines: 

climrpolyline-closed polyline 

Returns t if polyline is closed, otherwise returns nil. 

climrpolygon-points polygon 

Returns a sequence of points that specify the segments in polygon. 

climrmap-over-polygon-coordinates function polygon 

Applies function to all of the coordinates of the vertices of polygon. The 
function takes two arguments, the X and Y coordinates. 

climrmap-over-polygon-segments function polygon 

Applies function to the line segments that compose polygon. The function 
takes four arguments, the X and Y coordinates of the start of the line 
segment, and the X and Y coordinates of the end of the line segment. 



Lines in CLIM 
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A line is a special case of a polyline that has only a single segment. The functions 
for making and dealing with line are the following: 

climrline The protocol class that corresponds to a mathematical line-segment, that 
is, a polyline with only a single segment. This is a subclass of 
climrpolyline. 

clim:standard-line 

The standard class CLIM uses to implement lines. This is a subclass of 
climrline. This is the class that clim:make-line and climrmake-line* in- 
stantiate. 

clim:make-line start-point end-point 

Makes an object of class clim:standard-line that connects start-point to 
end-point. 

climrmake-line* start-x start-y end-x end-y 

Makes an object of class clim:standard-line that connects {start-x, 
start-y) to {end-x, end-y). 

clim:line-start-point line 

Returns the starting point of line. 

clim:line-end-point line 

Returns the ending point of line. 

climrline-start-point* line 

Returns the starting point of line as two values representing the coordi- 
nate pair. 

climrline-end-point* line 

Returns the ending point of line as two values representing the coordi- 
nate pair. 



Rectangles in CLIM 

A rectangle is a special case of a four-sided polygon whose edges are parallel to the 
coordinate axes. A rectangle can be specified completely by four real numbers 
{min-x, min-y, max-x, max-y). They are not closed under affine transformations. 
CLIM uses rectangles extensively for various purposes, particularly in optimiza- 
tions related to output recording. 

The functions for creating and dealing with rectangles are the following: 

climrrectangle 

The protocol class that corresponds to an axis-aligned mathematical 
rectangle, that is, rectangular polygons whose sides are parallel to the 
coordinate axes. This is a subclass of climrpolygon. 

climrstandard-rectangle 

The standard class CLIM uses to implement rectangles. This is a sub- 
class of climrrectangle. This is the class that climrmake-rectangle and 
climrmake-rectangle* instantiate. 
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climrmake-rectangle rain-point max-point 

Makes an object of class climrstandard-rectangle whose edges are paral- 
lel to the coordinate axes. 

climrmake-rectangle* min-x min-y max-x max-y 

Makes an object of class climrstandard-rectangle whose edges are paral- 
lel to the coordinate axes. 

climrrectangle-min-point rectangle 

Returns the minimum point of rectangle. The position of a rectangle is 
specified by its minimum point. 

climrrectangle-max-point rectangle 

Returns the maximum point of rectangle. (The position of a rectangle is 
specified by its minimum point). 

climrrectangle-edges* rectangle 

Returns the coordinate of the minimum X and Y and maximum X and Y 
of rectangle as four values. 

climrrectangle-min-x rectangle 

Returns the coordinate of the minimum X of rectangle. 

climrrectangle-min-y rectangle 

Returns the coordinate of the minimum Y of rectangle. 

climrrectangle-max-x rectangle 

Returns the coordinate of the maximum X of rectangle. 

climrrectangle-max-y rectangle 

Returns the coordinate of the maximum Y of rectangle. 

climrrectangle-width rectangle 

Returns the width of rectangle. The width of a rectangle is the difference 
between the maximum X and the minimum X. 

climrrectangle-height rectangle 

Returns the height of rectangle. The height is the difference between the 
maximum Y and the minimum Y. 

climrrectangle-size rectangle 

Returns two values, the width and the height of rectangle. 



Ellipses and Elliptical Arcs in CLIM 

An ellipse is an area that is the outline and interior of an ellipse. Circles are spe- 
cial cases of ellipses. 

An elliptical arc is a path consisting of all or a portion of the outline of an ellipse. 
Circular arcs are special cases of elliptical arcs. 

An ellipse is specified in a manner that is easy to transform, and treats all ellipses 
on an equal basis. An ellipse is specified by its center point and two vectors that 
describe a bounding parallelogram of the ellipse. The bounding parallelogram is 
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made by adding and subtracting the vectors from the center point in the following 
manner: 





x coordinate 


Y 


coordinate 


Center of Ellipse 


X 

c 


Y c 


Vectors 


dx, 
dx 2 


dy 1 

dy 2 


Corners of Paralellogram 


x + dx 1 + dx„ 

x + dx 1 - dx„ 

x - dx, - dx 
c 1 2 

X c - dx l + dx 2 


Y c 
Y c 
Y c 
Y c 


+ dy, + dy 2 
+ dy, - dy 2 

- dy 1 - dy 2 

- dy, + dy 2 



The special case of an ellipse with its axes aligned with the coordinate axes can be 
obtained by setting dx 2 and dy 1 to 0, or setting dx 1 and dy 2 to 0. 

Note that several different parallelograms specify the same ellipse, as shown here: 




One parallelogram is bound to be a rectangle 
and correspond to the semi-axes of the ellipse. 



the vectors will be perpendicular 



The following classes and functions are used to represent and operate on ellipses 
and elliptical arcs. 



climrellipse 



Class 



The protocol class that corresponds to a mathematical ellipse. This is a subclass of 
climrarea. If you want to create a new class that obeys the ellipse protocol, it 
must be a subclass of climrellipse. 



clim:elliptical-arc 



Class 



The protocol class that corresponds to a mathematical elliptical arc. This is a sub- 
class of climrpath. If you want to create a new class that obeys the elliptical arc 
protocol, it must be a subclass of clim:elliptical-arc. 



climrstandard-ellipse 



Class 
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The standard class CLIM uses to implement an ellipse. This is a subclass of 
climrellipse. This is the class that climrmake-ellipse and climrmake-ellipse* in- 
stantiate. 



clim:standard-elliptical-arc Class 

The standard class CLIM uses to implement an elliptical arc. This is a subclass of 
clim:elliptical-arc. This is the class that clim:make-elliptical-arc and climrmake- 
elliptical-arc* instantiate. 



Constructor Functions for Ellipses and Elliptical Arcs in CLIM 

climrmake-ellipse center-point radius-1-dx radius-1-dy radius-2-dx radius-2-dy &key 
:start-angle :end-angle 

Makes an object of class climrstandard-ellipse. The center of the ellipse 
is center-point. 

climrmake-ellipse* center-x center-y radius-1-dx radius-1-dy radius-2-dx radius-2-dy 
&key .start-angle :end-angle 

Makes an object of class climrstandard-ellipse. The center of the ellipse 
is (center-x, center-y). 

climrmake-elliptical-arc center-point radius-1-dx radius-1-dy radius-2-dx radius-2-dy 
&key .start-angle -.end-angle 

Makes an object of class climrstandard-elliptical-arc. The center of the 
ellipse is center-point. 

climrmake-elliptical-arc* center-x center-y radius-1-dx radius-1-dy radius-2-dx ra- 
dius-2-dy &key .start-angle -.end-angle 

Makes an object of class climrstandard-elliptical-arc. The center of the 
ellipse is (center-x, center-y). 



Accessors for CLIM Elliptical Objects 

The following accessor functions apply to both ellipses and elliptical arcs. In all 
cases, the name ellipse means that the argument is an ellipse or an elliptical arc. 

climrellipse-center-point ellipse 

Returns the center point of ellipse. 

climrellipse-center-point* ellipse 

Returns the center point of ellipse as two values representing the coordi- 
nate pair. 

climrellipse-radii ellipse 

Returns four values corresponding to the two radius vectors of ellipse. 

climrellipse-start-angle ellipse 

Returns the start angle of ellipse. 
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clim:ellipse-end-angle ellipse 

Returns the end angle of ellipse. 



Bounding Rectangles 

Every bounded region in CLIM has a derived bounding rectangle, which is the 
smallest rectangle that contains every point in the region, and may contain addi- 
tional points as well. Unbounded regions do not have any bounding rectangle. For 
example, all sheets and output records have bounding rectangles whose coordinates 
are relative to the bounding rectangle of the parent of the sheet or output record. 
See the section "Bounding Rectangles in CLIM". 

The following functions can be used to access the bounding rectangle of a region. 

climrbounding-rectangle* region 

Returns the bounding rectangle of region as four real numbers that spec- 
ify the left, top, right, and bottom edges of the bounding rectangle. 

climrbounding-rectangle region 

Returns a new bounding rectangle for region as a climrstandard- 
bounding-rectangle object. 

clim:bounding-rectangle-left region 

Returns the coordinate of the left edge of the bounding rectangle of re- 
gion. 

clim:bounding-rectangle-top region 

Returns the coordinate of the top edge of the bounding rectangle of re- 
gion. 

clim:bounding-rectangle-right region 

Returns the coordinate of the right edge of the bounding rectangle of re- 
gion. 

climrbounding-rectangle-bottom region 

Returns the coordinate of the bottom edge of the bounding rectangle of 
region. 

climrbounding-rectangle-position region 

Returns the position of the bounding rectangle of region as two values, 
the left and top coordinates of the bounding rectangle. 

clim:bounding-rectangle-set-position region x y 

Changes the position of the bounding rectangle of region to the new posi- 
tion x and y. 

clim:bounding-rectangle-size region 

Returns the size (as two values, width and height) of the bounding rect- 
angle of region. 

clim:bounding-rectangle-width region 

Returns the width of the bounding rectangle of region. 
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climrbounding-rectangle-height region 

Returns the height of the bounding rectangle of region. 

For example, the size of a the output generated by body can be determined by call- 
ing clim:bounding-rectangle-size on the output record: 

(let ((record (cl im:with-output-to-output-record (s) body))) 
(multiple-value-bind (width height) 

(cl im: bounding- rectangle-size record) 
(format t "~&Width is ~D, height is ~D" width height))) 



Pixmaps in CLIM 

A pixmap can be thought of as an "off-screen window", that is, a medium that can 
be used for graphical output, but is not visible on any display device. Pixmaps are 
provided to allow a programmer to generate a piece of output associated with some 
display device that can then be rapidly drawn on a real display device. For exam- 
ple, an electrical CAD system might generate a pixmap that corresponds to a com- 
plex, frequently used part in a VLSI schematic, and then use climrdraw-pixmap or 
clim:copy-from-pixmap to draw the part as needed. 

The exact representation of a pixmap is explicitly unspecified. Some mediums may 
not support pixmaps (such as PostScript mediums); in this case, CLIM will signal 
an error. 

Note that there is no interaction between most of the pixmap copying operations 
and output recording. That is, copying a pixmap onto an output recording is a 
pure drawing operation that affects only the display, not the output history. 

The following functions are provided for managing pixmaps: 

clim:copy-from-pixmap pixmap pixmap-x pixmap-y width height medium medium-x 
medium-y &optional (op boole-lj 

Copies the pixels from the pixmap pixmap starting at the position speci- 
fied by (pixmap-x,pixmap-y) into the medium medium at the position 
(medium-x,medium-y). op is a boolean operation that controls how the 
source and destination bits are combined. 

clim:copy-to-pixmap medium medium-x medium-y width height &optional pixmap 
(pixmap-x 0) (pixmap-y 0) (op boole-lj 

Copies the pixels from the medium medium starting at the position spec- 
ified by (medium-x,medium-y) into the pixmap pixmap at the position 
specified by (pixmap-x,pixmap-y) . op is a boolean operation that controls 
how the source and destination bits are combined. 

clim:copy-area medium from-x from-y width height to-x to-y &optional (op boole-lj 
Copies the pixels from the medium medium starting at the position spec- 
ified by (from-x,from-y) to the position (to-x,to-y) on the same medium, op 
is a boolean operation that controls how the source and destination bits 
are combined. 
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climrallocate-pixmap medium width height 

Allocates and returns a pixmap object that can be used on any medium 
that shares the same characteristics as medium. 

climrdeallocate-pixmap pixmap 

Deallocates the pixmap pixmap. 

clim:with-output-to-pixmap (medium-var medium &key .-width .-height) &body body 

Binds medium-var to a "pixmap medium", that is, a medium that does 
output to a pixmap with the characteristics appropriate to the medium 
medium, and then evaluates body in that context. All the output done to 
the medium designated by medium-var inside of body is drawn on the 
pixmap stream. 

climrdraw-pixmap medium pixmap point &rest args &key sink .-clipping-region 
.-transformation (.-function boole-lj 

Draws the pixmap pixmap on medium at the position point, creating a 
"pixmap output record" if medium is an output recording stream, .-func- 
tion is a boolean operation that controls how the source and destination 
bits are combined. 

climrdraw-pixmap* medium pixmap x y &rest args &key sink .-clipping-region 
.-transformation (.-function boole-lj 

Draws the pixmap pixmap on medium at the position (x,y), creating a 
"pixmap output record" if medium is an output recording stream, .-func- 
tion is a boolean operation that controls how the source and destination 
bits are combined. 

Try the following example, which creates a pixmap and then draws it on a stream 
wherever you click the pointer. 

(defun test-pixmaps (&optional (function boole-1) (stream xstandard-outputx)) 
(let* ((medium (cl im:sheet-medium stream)) 
(pixmap 

(cl im:with-output-to-pixmap (mv medium) 
(cl im:draw-ci rclex mv 50 50 20 

:filled t :ink (make-gray-col or 1/2)) 
(cl im:draw-rectanglex mv 100 100 

:filled nil)))) 
(block get-position 
(loop 

(cl im: tracking-pointer (stream) 
( :pointer-button-press (x y) 

(cl im:draw-pixmapx stream pixmap x y :function function)) 
(: key-press () 
(return-from get-position))))) 
pixmap)) 
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The CLIM Drawing Environment 

There are a number of factors that affect drawing in CLIM. Drawing is affected 
by transformations, style options, clipping, and by the ink which is used. All of 
these are controlled by the drawing environment. 

When you draw in CLIM, you do so on a medium. A medium can be thought of as 
a drawing surface. The medium also keeps track of its drawing environment, the 
current transformation, text style, foreground and background inks, etc. 

The drawing environment is dynamic. The CLIM facilities for affecting the draw- 
ing environment do so within their dynamic extent. For example, any drawing done 
by the function draw-stuff (as well as any drawing performed by anything it calls) 
below will be affected by the scaling transformation. 

(cl im:with-scal ing (medium 2 1) 
(draw-stuff medium)) 

The drawing environment is controlled through the use of drawing options. 



Components of CLIM Mediums 

Each CLIM medium contains components that correspond to the drawing options. 
These components provide the default values for the drawing options. When draw- 
ing functions are called and some options are unspecified, the options default to 
the values maintained by the medium. 

CLIM provides accessors for reading and writing the values of these components. 
Also, these components are temporarily bound within a dynamic context by using 
climrwith-drawing-options, clim:with-text-style, and related forms. Using setf of 
a component while it is temporarily bound takes effect immediately, but is undone 
when the dynamic context is exited. For convenience, these accessors generally 
work on sheets and streams as well as on mediums. 

climrmedium-foreground medium 

Returns the current foreground design of the medium. You can use setf 
on climrmedium-foreground to change the foreground design. 

climrmedium-background medium 

Returns the current background design of the medium. You can use setf 
on climrmedium-background to change the background design. 

climrmedium-ink medium 

Returns the current drawing ink of the medium. You can use setf on 
climrmedium-ink to change the current ink. 

climrmedium-transformation medium 

Returns the current transformation of the medium. You can use setf on 
climrmedium-transformation to change the current transformation. 

climrmedium-clipping-region medium 

Returns the current clipping region of the medium. You can use setf on 
climrmedium-clipping-region to change the clipping region. 
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clim:medium-line-style medium 

Returns the current line style of the medium. You can use setf on 
clim:medium-line-style to change the line style. 

clim:medium-text-style medium 

Returns the current text style of the medium. You can use setf on 
clim:medium-text-style to change the current text style. 

clim:medium-default-text-style medium 

The default text style for medium. You can use setf on climrmedium- 
default-text-style to change the default text style, but the text style 
must be a fully specified text style. 



Using CLIM Drawing Options 

Drawing options control various aspects of the drawing process. You can supply 
drawing options in a number of ways: 

• The medium (the destination for graphic output) itself has default drawing op- 
tions. If a drawing option is not supplied elsewhere, the medium supplies the 
value. See the section "Components of CLIM Mediums". 

• You can use climrwith-drawing-options and clim:with-text-style to temporarily 
bind the drawing options of the medium. In many cases, it is convenient to use 
climrwith-drawing-options to surround several calls to drawing functions, each 
using the same options. 

• You can supply the drawing options as keyword arguments to the drawing func- 
tions. These override the drawing options specified by climrwith-drawing- 
options. 

In some cases, it is important to distinguish between drawing options and subop- 
tions. Both text and lines have an option that controls the complete specification of 
the text and line style, and there are suboptions that affect one aspect of the text 
or line style. For example, the value of the rtext-style option is a text style object, 
which describes a complete text style consisting of family, face, and size. There 
are also suboptions called rtext-family, rtext-face, and rtext-size. Each suboption 
specifies a single aspect of the text style, while the option specifies the entire text 
style. Line styles are analogous to text styles; there is a rline-style option and 
some suboptions. 

In a given call to climrwith-drawing-options or a drawing function, normally you 
supply either the rtext-style option or a text style suboption (or more than one 
suboption), but you would not supply both. If you do supply both, then the text 
style comes from the result of merging the suboptions with the rtext-style option, 
and then merging that with the prevailing text style. 

climrwith-drawing-options (medium &key sink : clipping-region transformation 
■.line-style :line-unit :line-thickness :line-dashes :line-joint-shape :line-cap- 
shape :text-style :text-family :text-face :text-size) 
Binds the state of medium to correspond to the supplied drawing options, 
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and evaluates the body with the new drawing options in effect. Each op- 
tion causes binding of the corresponding component of the medium for 
the dynamic extent of the body. 



Set of CLIM Drawing Options 

The drawing options can be any of the following, plus any of the suboptions for 
line styles and text styles. 



rclipping-region Clim Drawing Option 

Specifies the region of the drawing plane on which the drawing functions can 
draw. 

The clipping region must be an climrarea; furthermore, an error might be sig- 
nalled if the clipping region is not a rectangle or a clim:region-set composed of 
rectangles. Drawing is clipped both by this clipping region and by other clipping 
regions associated with the mapping from the target drawing plane to the viewport 
that displays a portion of the drawing plane. The default is clim:+everywhere+, 
which means that no clipping occurs in the drawing plane, only in the viewport. 

The rclipping-region drawing option temporarily changes the value of 
climrmedium-clipping-region to climrregion-intersection of the argument and the 
previous value. If both a clipping region and a transformation are supplied in the 
same set of drawing options, the clipping region is transformed by the newly com- 
posed transformation. 



rink Clim Drawing Option 

A design used as the ink for drawing operations. The drawing functions draw with 
the color and pattern specified by the rink option, which can have any of the fol- 
lowing values: 

• climr+foreground-ink+, climr+background-ink+, or climr+flipping-ink+. 

• A color (created by climrmake-rgb-color or climrfind-named-color, for 

example). 

• An opacity (including climr+transparent-ink+). 

• A more general design, such as a pattern (created by 
climrmake-pattern) or a tile (created by climrmake-rectangular-tile). 

The default value is climr+foreground-ink+. 

The rink drawing option temporarily changes the value of climrmedium-ink and 
replaces the previous ink; the new and old inks are not combined in any way. 

For more information on how to use the rink drawing option, see the section 
"Drawing in Color in CLIM". 
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rtransformation Clim Drawing Option 

Transforms the coordinates used as arguments to drawing functions to the coordi- 
nate system of the drawing plane. The default value is climr+identity- 
tr ansf ormation+ . 

The rtransformation drawing option temporarily changes the value of 

climrmedium-transformation to climrcompose-transformations of the argument 
and the previous value. 



rtext-style Clim Drawing Option 

Controls how text is displayed, both for the graphic drawing functions and ordi- 
nary stream output. The value of the rtext-style option is a text style object. 

This drawing option temporarily changes the value of climrmedium-text-style to 
the result of merging the value of rtext-style with the prevailing text style. 

If text style suboptions are also specified, they temporarily change the value of 
climrmedium-text-style to the result of merging the specified suboptions with the 
rtext-style drawing options, which is then merged with the previous value of 
climrmedium-text-style. 

See the section "CLIM Text Style Suboptions". 



rline-style Clim Drawing Option 

Controls how lines and arcs are drawn. The value of the rline-style option is a line 
style object. 

This drawing option temporarily changes the value of climrmedium-line-style. 

See the section "CLIM Line Style Suboptions". 

For the set of line and text style options, see the section "CLIM Line Style Subop- 
tions" , and see the section "CLIM Text Style Suboptions". 



Using the rfilled Option to Certain CLIM Drawing Functions 

Certain drawing functions can draw either an area or the outline of that area. 
This is controlled by the rfilled keyword argument to these functions. If the value 
is t (the default), then the function paints the entire area. If the value is nil, then 
the function strokes the outline of the area under the control of the line-style 
drawing option. 

The rfilled keyword argument is not a drawing option and cannot be specified to 
climrwith-drawing-options. 

These are functions that have a rfilled keyword argument: 

climrdraw-rectangle 

climrdraw-rectangle* 

climrdraw-rectangles 
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climrdraw-rectangles* 

climrdraw-polygon 

climrdraw-polygon* 

climrdraw-circle 

climrdraw-circle* 

climrdraw-ellipse 

climrdraw-ellipse* 



Line Styles in CLIM 

A line or other path is a one-dimensional object. In order to be visible, the render- 
ing of a line must, however, occupy some non-zero area on the display hardware. A 
line style object is used to represent the advice that CLIM supplies to the render- 
ing substrate on how to perform the rendering. 



CLIM Line Style Objects 

It is often useful to create a line style object that represents a style you wish to 
use frequently, rather than continually specifying the corresponding line style sub- 
options. 

The class of a line style object is clim:line-style. You create a line style object 
with clim:make-line-style. 

clim:make-line-style &key (:unit mormalj (.-thickness I) sdashes (:joint-shape rmiter) 
(xap-shape rbutt) 
Creates a line style object with the supplied characteristics. 

The following readers are provided for the components of line styles: 

clim:line-style-thickness line-style 

Returns the thickness component of a line style object, which is an inte- 
ger. 

clim:line-style-dashes line-style 

Returns the dashes component of a line style object. 

clim:line-style-joint-shape line-style 

Returns the joint shape component of a line style object. 

clim:line-style-cap-shape line-style 

Returns the cap shape component of a line style object. 

clim:line-style-unit line-style 

Returns the unit component of a line style object, which will be one of 
mormal or rpoint. 



CLIM Line Style Suboptions 
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Each line style suboption has a reader function which returns the value of that 
component from a line style object. 

The line style suboptions are listed as follows: 



:line-thickness Clim Drawing Option 

The thickness (an integer in the units described by clim:line-style-unit) of the 
lines or arcs drawn by a drawing function. The default is 1, which combined with 
the default unit of rnormal, means that the default line drawn is the "comfortably 
visible thin line". 

You can call clim:line-style-thickness on a line style object to get the value of the 
:line-thickness, or rthickness component. 



:line-dashes Clim Drawing Option 

Controls whether lines or arcs are drawn as dashed figures, and if so, what the 
dashing pattern is. Possible values are: 

nil Lines are drawn solid, with no dashing. This is the default. 

t Lines are drawn dashed, with a dash pattern that is unspecified and 

may vary with the rendering substrate. This allows the underlying 
display substrate to provide a default dashed line for the user whose 
only requirement is to draw a line that is visually distinguished 
from the default solid line. Using the default dashed line can be 
more efficient than specifying customized dashes. 

sequence Specifies a sequence of integers, usually a vector, controlling the 
dash pattern of a drawing function. It is an error if the sequence 
does not contain an even number of elements. The elements of the 
sequence are lengths of individual components of the dashed line or 
arc. The odd elements specify the length of inked components, the 
even elements specify the gaps. All lengths are expressed in the 
units described by clim:line-style-unit. You can use climrmake- 
contrasting-dash-patterns to create a a sequence for the : dashes 
option. 

See the function clim:make-contrasting-dash-patterns. 

You can call clim:line-style-dashes on a line style object to get the value of the 
:line-dashes, or : dashes component. 



:line-joint-shape Clim Drawing Option 

Specifies the shape of joints between line segments of closed, unfilled figures, 
when the :line-thickness or rthickness option to a drawing function is greater 
than 1. The possible shapes are rmiter, rbevel, rround, and rnone; the default is 
rmiter. 
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Note that the joint shape is implemented by the host window system, so not all 
platforms will necessarily fully support it. 

You can call clim:line-style-joint-shape on a line style object to get the value of 
the :line-joint-shape, or :joint-shape component. 



:line-cap-shape Clim Drawing Option 

Specifies the shape for the ends of lines and arcs drawn by a drawing function, 
one of :butt, rsquare, rround, or :no-end-point. The default is :butt. Note that 
the cap shape is implemented by the host window system, so not all platforms will 
necessarily fully support it. 

You can call clim:line-style-cap-shape on a line style object to get the value of the 
:line-cap-shape, or :cap-shape component. 



:line-unit Clim Drawing Option 

The units in which the thickness, dash pattern, and dash phase are measured. Pos- 
sible values are rnormal and rpoint, described as follows: 

rnormal A relative measure in terms of the usual or "normal" line thick- 
ness. The normal line thickness is the thickness of the "comfortably 
visible thin line", which is a property of the underlying rendering 
substrate. This is the default. 

rpoint An absolute measure in terms of printer's points (approximately 
1/72 of an inch). 

You can call clim:line-style-unit on a line style object to get the value of the rline- 
unit or runit component. 

This function can be used to generate a value for the : dashes line style suboption. 

clim:make-contrasting-dash-patterns n &optional k 

Makes a simple vector of n dash patterns with recognizably different ap- 
pearances. If k (an integer between and n-1) is supplied, climrmake- 
contrasting-dash-patterns returns the £'th dash pattern. If the imple- 
mentation does not have n different contrasting dash patterns, 
clim:make-contrasting-dash-patterns signals an error. 

clim:contrasting-dash-patterns-limit port 

Returns the number of contrasting dash patterns that the port port can 
generate. 



Text Styles in CLIM 

CLIM's model for the appearance of text follows the same principle as the model 
for creating formatted output. This principle holds that the application program 
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should describe how the text should appear in high-level terms, and that CLIM 
will take care of the details of choosing a specific device font. This approach em- 
phasizes portability. 



Concepts of CLIM Text Styles 

In CLIM, you specify the appearance of text by giving it an abstract text style. 
Each CLIM medium defines a mapping between these abstract style specifications 
and particular device-specific fonts. At runtime, CLIM chooses an appropriate de- 
vice font to represent the characters. 

A text style is a combination of three characteristics that describe how characters 
appear. Text style objects have components for family, face, and size. 

family Characters of the same family have a typographic integrity, so 

that all characters of the same family resemble one another. 
One of :fix, rserif, :sans-serif, or nil. 

face A modification of the family, such as bold or italic. One of 

rroman (meaning normal), :bold, ritalic, (:bold ritalic), or nil. 

size The size of the character. One of the logical sizes (:tiny, 

:very-small, :small, rnormal, rlarge, :very-large, :huge, 
rsmaller, rlarger), or a real number representing the size in 
printer's points, or nil. 

Not all of these attributes need be specified for a given text style object. Text 
styles can be merged in much the same way as pathnames are merged; unspecified 
components in the style object (that is, components that have nil in them) may be 
filled in by the components of a "default" style object: 

clim:*default-text-style* 

The default text style used by all streams. 

The sizes rsmaller and rlarger are treated specially in that they are merged with 
the default text style size to result in a size that is discernably smaller or larger. 
For example, a text style size of rlarger would merge with a default text size of 
: small to produce the resulting size rnormal. 

Some systems include color in their notion of a text style. This is not the case in 
CLIM. If you want to change the color of textual output, use the rink option to 
climrdraw-text*, or if you are using functions like write-string or format, use the 
rink option to climrwith-drawing-options. 

A text style object is called fully specified if none of its components is nil, and the 
size component is not a relative size (that is, is neither rsmaller nor rlarger). 

When text is displayed on a medium, the text style is mapped to some medium 
specific description of the glyphs for each character. This description is usually 
that medium's concept of a font object. This mapping is mostly transparent to the 
application developer, but it is worth noting that not all text styles have mappings 
associated with them on all media. If the text style used does not have a mapping 
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associated with it on the given medium, a special text style reserved for this case 
will be used. 



CLIM Text Style Objects 

It is often useful to create a text style object that represents a style you wish to 
use frequently, rather than continually specifying the corresponding text style sub- 
options. 

For example, you might want to have a completely different family, face and size 
for menus. You could make a text style object and make it be the value of *menu- 
text-style*. 

You create text style objects using clim:make-text-style. 

(cl im:with-text-style 

(my-stream (cl im: make-text-style :fix :bold :large)) 
(write-string my-stream "Here is a text-style example.")) 

Here is a text-style exanple. 

=> 

In the current implementation of CLIM, text style objects are interned. That is, 
two different invocations of clim:make-text-style with the same combination of 
family, face and size will result in the same (in the sense of eq) text style object. 
For this reason, you should not modify text style objects. 



CLIM Text Style Suboptions 

You can use text style suboptions to specify characteristics of a text style object. 
Each text style suboption has a reader function which returns the current value of 
that component from a text style object. 

The text style suboptions are: 



:text-family Clim Drawing Option 

Specifies the family of the text style. The reader function is clim:text-style-family. 

:text-face Clim Drawing Option 

Specifies the face of the text style. The reader function is clim:text-style-face. 

:text-size Clim Drawing Option 

Specifies the size of the text style. The reader function is clim:text-style-size. 
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CLIM Text Style Functions 

The following functions can be used to parse, merge, and create text style objects, 
and read the components of the objects. 

clim:parse-text-style text-style 

Returns the text style object representing the text style described by text- 
style. 

clim:merge-text-styles stylel style2 

Merges stylel against the defaults provided by style2. 

clim:text-style-components text-style medium 

Returns the components of text-style as three values (family, face, and 
size). 

clim:text-style-family text-style 

Returns the family component of the text-style. 

clim:text-style-face text-style 

Returns the face component of the text-style. 

clim:text-style-size text-style 

Returns the size component of the text-style. 

clim:text-style-ascent text-style medium 

The ascent (a real number) of text-style as it would be rendered on medi- 
um. 

clim:text-style-descent text-style medium 

The descent (a real number) of text-style as it would be rendered on 
medium. 

clim:text-style-height text-style medium 

Returns the height (a real number) of the "usual character" in text-style 
on medium. 

clim:text-style-width text-style medium 

Returns the width (a real number) of the "usual character" in text-style 
on medium. 

clim:text-style-fixed-width-p text-style medium 

Returns t if text-style will map to a fixed-width font on medium, other- 
wise returns nil. 

clim:text-style-mapping port style &optional character-set 

Returns the font object that will be used if characters in character-set in 
the text style style are drawn on any medium on the port port. 

clim:text-style-mapping-exists-p port style &optional character-set exact-size-required 

Returns t if there is a font associated with the text style style on the 
port port, otherwise returns nil. 
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clim:make-text-style family face size 

Creates a text style object with the given family, face, and style. 

The following forms can be used to change the current text style for a stream by 
merging the specified style with the stream's current text style. They are intended 
as abbreviations to be used instead of climrwith-drawing-options. 

clim:with-text-style (medium style) &body body 

Binds the current text style of medium to correspond to the new text 
style, within the body, style is a text style object. 

clim:with-text-face (medium face) &body body 

Binds the current text face of medium to correspond to the new text face 
face, within the body. 

clim:with-text-family (medium family) &body body 

Binds the current text family of medium to correspond to the new text 
family family, within the body. 

clim:with-text-size (medium size) &body body 

Binds the current text size of medium to correspond to the new text size 
size, within the body. 



Transformations in CLIM 

One of the features of CLIM's graphical capabilities is the use of coordinate sys- 
tem transformations. By using transformations you can often write simpler graph- 
ics code, because you can choose a coordinate system in which to express the 
graphics that simplifies the description of the drawing. 

A transformation is an object that describes how one coordinate system is related 
to another. A graphic function performs its drawing in the current coordinate sys- 
tem of the stream or medium. A new coordinate system is defined by describing its 
relationship to the old one (the transformation). The drawing can now take place 
in the new coordinate system. The basic concept of graphic transformations is il- 
lustrated in Figure42. 

For example, you might define the coordinates of a five-pointed star, and a func- 
tion to draw it. 

(defvar *star* '(032-3-3 1/2 3 1/2 -2 -3)) 

(defun draw-star (stream) 

(cl im: draw-polygon* stream xstarx :closed t : filled nil)) 

Without any transformation, the function draws a small star centered around the 
origin. By applying a transformation, the same function can be used to draw a star 
of any size, anywhere. For example: 
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Transformation 




The Transformed Coordinate System 



The Original Coordinate System 





Original Graphics 



Graphics under the Transformation 



Figure 63. Graphic Transformation 

(cl im:with-room-for-graphics (stream) 
(cl im:with-translation (stream 100 100) 
(cl im:with-scal ing (stream 10) 
(draw-star stream))) 
(cl im:with-translation (stream 240 110) 
(cl im:with-rotation (stream -0.5) 
(cl im:with-scal ing (stream 12 8) 
(draw-star stream))))) 

will draw a picture somewhat like the lower half of Figure 63 on stream. 



The Transformations Used by CLIM 

The type of transformations that CLIM uses are called affine transformations. An 
affine transformation is a transformation that preserves straight lines. In other 
words, if you take a number of points that fall on a straight line and apply an 
affine transformation to their coordinates, the transformed coordinates will fall on 
a straight line in the new coordinate system. Affine transformations include trans- 
lations, scalings, rotations, and reflections. 
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A translation is a transformation that preserves length, angle, and orientation of 
all geometric entities. 

A rotation is a transformation that preserves length and angles of all geometric 
entities. Rotations also preserve one point and the distance of all entities from that 
point. You can think of that point as the "center of rotation" — it is the point 
around which everything rotates. 

There is no single definition of a scaling transformation. Transformations that pre- 
serve all angles and multiply all lengths by the same factor (preserving the 
"shape" of all entities) are certainly scaling transformations. However, scaling is 
also used to refer to transformations that scale distances in the X direction by one 
amount and distances in the Y direction by another amount. 

A reflection is a transformation that preserves lengths and magnitudes of angles, 
but changes the sign (or "handedness") of angles. If you think of the drawing 
plane on a transparent sheet of paper, a reflection is a transformation that "turns 
the paper over". 

If we transform from one coordinate system to another, and then from the second 
to a third coordinate system, we can regard the resulting transformation as a sin- 
gle transformation resulting from composing the two component transformations. It 
is an important and useful property of affine transformations that they are closed 
under composition. 

Note that composition is not commutative; in general, the result of applying trans- 
formation A and then applying transformation B is not the same as applying B 
first, then A. 

Any arbitrary transformation can be built up by composing a number of simpler 
transformations, but that same transformation can often be constructed by a differ- 
ent composition of different transformations. 

Transforming a region applies a coordinate transformation to that region, thus 
moving its position on the drawing plane, rotating it, or scaling it. Note that 
transforming a region creates a new region; it does not side-effect the region ar- 
gument. 

The user interface to transformations is the rtransformation option to the draw- 
ing functions. Users can create transformations with constructors; see the section 
"CLIM Transformation Constructors". The other operators documented in this sec- 
tion are used by CLIM itself, and are not often needed by users. 



CLIM Transformation Constructors 

The following functions can be used to create a transformation object that can be 
used, for instance, in a call to climrcompose-transformations. 

climrmake-translation-transformation delta-x delta-y 

Makes a transformation that translates all points by delta-x in the X di- 
rection and delta-y in the Y direction. 
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climrmake-rotation-transformation angle &optional origin 

Makes a transformation that rotates all points clockwise by angle around 
the point origin. The angle is specified in radians. If origin is supplied it 
must be a point; if not supplied it defaults to (0,0). 

climrmake-rotation-transformation* angle origin-x origin-y 

Makes a transformation that rotates all points clockwise by angle around 
the point, {origin-x, origin-y). The angle is specified in radians. 

climrmake-scaling-transformation mx my &optional origin 

Makes a transformation that multiplies the X-coordinate distance of ev- 
ery point from origin by mx and the Y-coordinate distance of every point 
from origin by my. If origin is supplied it must be a point; if not sup- 
plied it defaults to (0,0). 

climrmake-scaling-transformation* mx my origin-x origin-y 

Makes a transformation that multiplies the X-coordinate distance of ev- 
ery point from origin-x by mx and the Y-coordinate distance of every 
point from origin-y by my. 

climrmake-reflection-transformation point-1 point-2 

Makes a transformation that reflects every point through the line pass- 
ing through the points point-1 and point-2. 

climrmake-reflection-transformation* xl yl x2 y2 

Makes a transformation that reflects every point through the line pass- 
ing through the points (xl, yl) and (x2, y2). 

climrmake-transformation mxx mxy myx myy tx ty 

Makes a general transformation whose effect is: 

x' = m xx x + m xy y + t x 

y' = m yx x + m yy y + t y 

Where x and y are the coordinates of a point before the transformation 
and x' and y' are the coordinates of the corresponding point after. 

clim:make-3-point-transformation point-1 point-2 point-3 point-1-image points- 
image point-3-image 

Makes a transformation that takes point-1 into point- 1-image, point-2 into 
point-2-image and point-3 into point-3-image. (Three non-collinear points 
and their images under the transformation are enough to specify any 
affine transformation.) If the points are collinear, the 
climrtransformation-underspecified condition is signalled. 

clim:make-3-point-transformation* xl yl x2 y2 x3 y3 xl-image yl-image x2-image 
y2-image x3-image y3-image 

Makes a transformation that takes (xl, yl) into (xl-image, yl-image), (x2, 
y2) into (x2-image, y2-image) and (x3, y3) into (x3-image, y3-image). 
(Three non-collinear points and their images under the transformation 
are enough to specify any affine transformation.) If the points are 
collinear, the climrtransformation-underspecified condition is signalled. 
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CLIM Transformation Protocol 



climrtransformation Class 

The protocol class for all transformations. There are one or more subclasses of 
climrtransformation with implementation-dependent names that implement trans- 
formations. If you want to create a new class that obeys the transformation proto- 
col, it must be a subclass of climrtransformation. 



climr+identity-transformation+ Constant 

An instance of a transformation that is guaranteed to be an identity transforma- 
tion, that is, the transformation that "does nothing". 



CLIM Transformation Predicates 

The following predicates are provided in order to be able to determine whether or 
not a transformation has a particular characteristic. 

climrtransformation-equal transforml transform2 

Returns t if the two transformations have equivalent effects (that is, are 
mathematically equal), otherwise returns nil. 

climridentity-transformation-p transform 

Returns t if transform is equal (in the sense of climrtransformation- 
equal) to the identity transformation, otherwise returns nil. 

climrtranslation-transformation-p transform 

Returns t if transform is a pure translation, that is a transformation that 
moves every point by the same distance in X and the same distance in Y, 
otherwise returns nil. 

climrinvertible-transformation-p transform 

Returns t if transform has an inverse, otherwise returns nil. 

climrreflection-transformation-p transform 

Returns t if transform inverts the "handedness" of the coordinate sys- 
tem, otherwise returns nil. 

climrrigid-transformation-p transform 

Returns t if transform transforms the coordinate system as a rigid ob- 
ject, that is, as a combination of translations, rotations, and pure reflec- 
tions. Otherwise, it returns nil. 

climreven-scaling-transformation-p transform 

Returns t if transform multiplies all X-lengths and Y-lengths by the same 
magnitude, otherwise returns nil. This includes pure reflections through 
vertical and horizontal lines. 

climrscaling-transformation-p transform 

Returns t if transform multiplies all X-lengths by one magnitude and all 
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Y-lengths by another magnitude, otherwise returns nil. This category in- 
cludes even scalings as a subset. 

clim:rectilinear-transformation-p transform 

Returns t if transformation will always transform any axis-aligned rect- 
angle into another axis-aligned rectangle, otherwise returns nil. This cat- 
egory includes scalings as a subset, and also includes 90 degree rota- 
tions. 



CLIM Transformation Functions 

The following functions can be used to compose transformations. The "compose 
with" functions have exactly the same effect as climrcompose-transformations, 
except that they are more efficient. 

climrcompose-transformations transforml transform2 

Returns a transformation that is the composition of its arguments. Com- 
position is in right-to-left order, that is the resulting transformation rep- 
resents the effects of applying transform2 followed by transforml. 

clim:compose-translation-with-transformation transform dx dy 

Creates a new transformation by composing transform with a given 
translation, as specified by dx and dy. The order of composition is that 
the translation "transformation" is first, followed by transform. 

clim:compose-rotation-with-transformation transform angle &optional origin 

Creates a new transformation by composing transform with a given rota- 
tion, as specified by angle and origin. The order of composition is that 
the rotation "transformation" is first, followed by transform. 

clim:compose-scaling-with-transformation transform mx my &optional origin 

Creates a new transformation by composing transform with a given scal- 
ing, as specified by mx, my, and origin. The order of composition is that 
the scaling "transformation" is first, followed by transform. 

clim:compose-transformation-with-translation transform dx dy 

Creates a new transformation by composing the translation given by dx 
and dy with transform. The order of composition is that transform is 
first, followed by the translation "transformation". 

clim:compose-transformation-with-rotation transform angle &optional origin 

Creates a new transformation by composing the rotation given by angle 
and origin with transform. The order of composition is that transform is 
first, followed by the rotation "transformation". 

clim:compose-transformation-with-scaling transform mx my &optional origin 

Creates a new transformation by composing the scaling given by mx, my, 
and origin with transform. The order of composition is that transform is 
first, followed by the scaling "transformation". 

climrinvert-transformation transform 

Returns a transformation that is the inverse of transform. The result of 
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composing a transformation with its inverse is the identity transforma- 
tion. If transform is singular, climrinvert-transformation signals the 
climrsingular-transformation condition. 

The following three forms can be used to compose a transformation into the cur- 
rent transformation of a stream. They are intended as abbreviations for calling 
climrcompose-transformations and climrwith-drawing-options directly. 

climrwith-rotation (medium angle &optional origin) &body body 

Establishes a rotation on medium that rotates clockwise by angle (in ra- 
dians), and then evaluates body with that transformation in effect. If ori- 
gin is supplied, the rotation is about that point. The default for origin is 
(0,0). 

climrwith-translation (medium dx dy) &body body 

Establishes a scaling transformation on medium that scales by dx in the 
X direction and dy in the Y direction, and then evaluates body with that 
transformation in effect. 

climrwith-scaling (medium sx &optional sy) &body body 

Establishes a scaling transformation on medium that scales by sx in the 
X direction and sy in the Y direction, and then evaluates body with that 
transformation in effect. If sy is not supplied, it defaults to sx. 

These three functions also compose a transformation into the current transforma- 
tion of a stream, but have more complex behavior. 

clim:with-room-for-graphics f&optional stream &key .-height Ofirst-quadrant t) 
(■move-cursor t) :record-type) &body body 

Binds the dynamic environment to establish a local coordinate system for 
doing graphics output. 

clim:with-local-coordinates f&optional stream x y) &body body 

Binds the dynamic environment to establish a local coordinate system 
with the positive X-axis extending to the right and the positive Y-axis ex- 
tending downward, with (0,0) at the current cursor position of stream. 

clim:with-first-quadrant-coordinates f&optional stream x y) &body body 

Binds the dynamic environment to establish a local coordinate system 
with the positive X-axis extending to the right and the positive Y-axis ex- 
tending upward, with (0,0) at the current cursor position of stream. 



Applying CLIM Transformations 

The following functions can be used to apply a transformation to some sort of a 
geometric object, such as a region or a distance. Calling climrtransform-position 
or climruntransform-position on a spread points is generally more efficient than 
calling climrtransform-region or climruntransform-region on the unspread point 
object. 
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climrtransform-region transformation region 

Applies transformation to region, and returns a new transformed region. 

climruntransform-region transformation region 

Applies the inverse of transformation to region and returns a new trans- 
formed region. 

climrtransform-position transform x y 

Applies transform to the point whose coordinates are x and y, and re- 
turns two values, the transformed X-coordinate and the transformed 
Y-coordinate. 

climruntransform-position transform x y 

Applies the inverse of transform to the point whose coordinates are x and 
y, and returns two values, the transformed X-coordinate and the trans- 
formed Y-coordinate. 

climrtransform-rectangle* transform xl yl x2 y2 

Applies the transformation transform to the rectangle specified by the 
four coordinate arguments, which are real numbers. One corner of the 
rectangle is at (xl,yl) and the opposite corner is at (x2,y2). 

climruntransform-rectangle* transform xl yl x2 y2 

Applies the inverse of transform to the rectangle specified by the four 
coordinate arguments, and returns four values that specify the minimum 
and maximum points of the transformed rectangle. 

climrtransform-distance transform dx dy 

Applies transform to the distance represented by dx and dy, and returns 
two values, the transformed dx and the transformed dy. 

climruntransform-distance transform dx dy 

Applies the inverse of transform to the distance represented by dx and 
dy, and returns two values, the transformed dx and the transformed dy. 

climrtranslate-coordinates x-delta y-delta &body coordinate-pairs 

Translates each of the X and Y coordinate pairs in coordinate-pairs by 
x-delta and y-delta. 



Drawing in Color in CLIM 



Concepts of Drawing in Color in CLIM 

To draw in color, you can supply the rink drawing option to CLIM's drawing func- 
tions when using streams opened on a color port (see the section "Functions for 
Operating on Windows Directly" ) 

The drawing functions work by selecting a region of the drawing plane and paint- 
ing it with color. 
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The region to be painted is the intersection of the shape specified by the drawing 
function and the rclipping-region drawing option, which is then transformed by 
the rtransformation drawing option. The shape can be a graphical area (such as a 
rectangle or an ellipse), a path (such as a line segment or the outline of an el- 
lipse), or the letterforms of text. 

Use the rink drawing option to specify how to color this region. The value for rink 
is usually a color, but you can also specify a design for rink. When you use a de- 
sign for rink, you can control the coloring-in process by specifying a new color of 
the drawing plane for each ideal point in the shape being drawn. (This can depend 
on the coordinates of the point, and on the current color at that point in the draw- 
ing plane). For more information, see the section "Drawing with Designs in CLIM". 

Along with its drawing plane, a medium has a foreground and a background. The 
foreground is the default ink when the rink drawing option is not specified. The 
background is drawn all over the drawing plane before any output is drawn. You 
can erase by drawing the background over the region to be erased. You can change 
the foreground or background at any time. This changes the contents of the draw- 
ing plane. The effect is as if everything on the drawing plane is erased, the back- 
ground is drawn on the entire drawing plane, and then everything that was ever 
drawn (provided it was saved in the output history) is redrawn using the new fore- 
ground and background. 

Color Objects 

A color in CLIM is an object representing the intuitive definition of color: white, 
black, red, pale yellow, and so forth. The visual appearance of a single point is 
completely described by its color. 

A color can be specified by three real numbers between and 1 inclusive, giving 
the amounts of red, green, and blue. Three O's mean black; three l's mean white. 
A color can also be specified by three numbers giving the intensity, hue, and satu- 
ration. A totally unsaturated color (a shade of gray) can be specified by a single 
real number between and 1, giving the amount of white. 

You can obtain a color object by calling one of climrmake-rgb-color, climrmake- 
ihs-color, or climrmake-gray-color, or by using one of the predefined colors listed 
in "Predefined Color Names in CLIM". Specifying a color object as the rink draw- 
ing option, the foreground, or the background causes CLIM to use that color in the 
appropriate drawing operations. 

Rendering 

When CLIM renders the graphics and text in the drawing plane onto a real display 
device, physical limitations of the display device force the visual appearance to be 
an approximation of the drawing plane. Colors that the hardware doesn't support 
might be approximated by using a different color, or by using a stipple pattern. 
Even primary colors such as red and green can't be guaranteed to have distinct vi- 
sual appearance on all devices, so if device independence is desired it is best to 
use climrmake-contrasting-inks rather than a fixed palette of colors. 
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The region of the display device that gets colored when rendering a path or text is 
controlled by the line-style or text-style, respectively. 



CLIM Operators for Drawing in Color 

clim:make-ihs-color intensity hue saturation 

Creates a color object with the specified intensity, hue, and saturation. 

clim:make-rgb-color red green blue 

Creates a color object with color components red, green, and blue. 

clim:make-gray-color luminosity 

Creates a color object, luminosity is for black, 1 for white, in between 
for gray. 

clim:color-ihs color 

Returns three values, the intensity, hue, and saturation components of 
color. 

clim:color-rgb color 

Returns three values, the red, green, and blue components of color. The 
values are real numbers between and 1 (inclusive). 

clim:make-contrasting-inks n &optional k 

Returns a simple vector of n inks with different appearances. If k (an in- 
teger between and n-1) is supplied, clim:make-contrasting-inks re- 
turns the £'th design. 

clim:contrasting-inks-limit port 

Returns the number of contrasting inks that the port port can generate. 



Predefined Color Names in CLIM 

The color corresponding to the color names can be found by calling climrfind- 
named-color, which looks the color name up in an object called a palette. A palette 
is a table that maps color names to color objects. On some platforms, the palette 
has a bounded size (typically around 256 entries), and serves as a way to allocate a 
colormap resource. 

clim:find-named-color name palette &key :errorp 

Finds the color named name in the palette palette. 

climrframe-palette frame 

Returns the palette associated with the application frame frame. 

climrframe-manager-palette frame-manager 

Returns the palette that will be used, by default, by all the frames man- 
aged by frame-manager, if those frame's don't have a palette of their 
own. 

climrport-default-palette port 

Returns the palette associated with the port port. 
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clim:palette-color-p palette 

Returns t if the palette supports color, otherwise returns nil. 

The following table lists the basic set of named colors in the default palette. You 
can look up one of these colors, for example, by doing 

(dim: find-named-col or "lavender" 

(cl im: frame-palette cl im:*appl i cat ion- frame*)) 

Applications can define other colors, but these are provided because they are com- 
monly used in the X Windows community (not because there is anything special 
about these particular colors). This table is a subset of the colors listed in the file 
/X11/R4/mit/rgb/rgb.txt, from the Xll R4 distribution. 
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al ice-blue 

azure 

black 

blue-violet 

cadet-blue 

coral 

cyan 

dark-khaki 

dark-orchid 

dark-slate-blue 

dark-violet 

dim-gray 

floral-white 

ghost-white 

gray 

honeydew 

ivory 

lavender-blush 

1 ight-blue 

1 ight-goldenrod 

1 ight-pink 

1 ight-sky-blue 

1 ight-steel-blue 

1 inen 

medium-aquamarine 

medium-purple 

medium-spring-green 

midnight-blue 

moccasin 

old-lace 

orange-red 

pale-green 

papaya-whip 

pink 

purple 

royal -blue 

sandy-brown 

sienna 

slate-gray 

steel-blue 

tomato 

violet-red 

white-smoke 



antique-white 

beige 

blanched-almond 

brown 

chartreuse 

cornflower-blue 

dark-goldenrod 

dark-ol ive-green 

dark-salmon 

dark-slate-gray 

deep-pink 

dodger-blue 

forest-green 

gold 

green 

hot-pink 

khaki 

lawn-green 

1 ight-coral 

1 i ght-gol denrod-yel 1 ow 

1 ight-salmon 

1 ight-slate-blue 

1 ight-yel low 

magenta 

medium-blue 

medium-sea-green 

medium-turquoise 

mint-cream 

navajo-white 

ol ive-drab 

orchid 

pale-turquoise 

peach-puff 

plum 

red 

saddle-brown 

sea-green 

sky-blue 

snow 

tan 

turquoise 

wheat 

yel low 



aquamarine 

bisque 

blue 

burlywood 

chocolate 

cornsilk 

dark-green 

dark-orange 

dark-sea-green 

dark-turquoise 

deep-sky-blue 

f i rebrick 

gainsboro 

goldenrod 

green-yel low 

indian-red 

lavender 

lemon-chiffon 

1 ight-cyan 

light-gray 

1 ight-sea-green 

1 ight-slate-gray 

1 ime-green 

maroon 

medium-orchid 

medi um-sl ate-bl ue 

medi um-vi ol et-red 

misty-rose 

navy-blue 

orange 

pale-goldenrod 

pale-violet-red 

peru 

powder-blue 

rosy-brown 

salmon 

seashel 1 

slate-blue 

spring-green 

thistle 

violet 

white 

yel low-green 



In addition to these named colors, CLIM also provides constants for the primary 
colors: clim:+black+, clim:+white+, clim:+red+, clim:+green+, clim:+blue+, 
clim:+cyan+, clim:+yellow+, and clim:+magenta+. 
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Drawing with Designs in CLIM 



Concepts of Designs in CLIM 

A design is an object that represents a way of arranging colors and opacities in 
the drawing plane. The simplest kind of design is a color, which simply places a 
constant color at every point in the drawing plane. See the section "Drawing in 
Color in CLIM". 

This chapter describes more complex kinds of design, which place different colors 
at different points in the drawing plane or compute the color from other informa- 
tion, such as the color previously at that point in the drawing plane. Not all of the 
features described in this chapter are supported in the present implementation. 

Recall that the drawing functions work by selecting a region of the drawing plane 
and painting it with color, and that the rink drawing option specifies how to color 
this region. The value of the rink drawing option can be any kind of design, any 
member of the class climrdesign. The values of climrmedium-foreground, 
climrmedium-background, and climrmedium-ink are also designs. Not all designs 
are supported as the arguments to the rink drawing option, or as a foreground or 
background in the present implementation. 

A design can be characterized in several different ways: 

All designs are either bounded or unbounded. Bounded designs are transparent ev- 
erywhere beyond a certain distance from a certain point. Drawing a bounded de- 
sign has no effect on the drawing plane outside that distance. Unbounded designs 
have points of non-zero opacity arbitrarily far from the origin. Drawing an un- 
bounded design affects the entire drawing plane. 

All designs are either uniform or non-uniform. Uniform designs have the same 
color and opacity at every point in the drawing plane. Uniform designs are always 
unbounded, unless they are completely transparent. 

All designs are either solid or translucent. At each point a solid design is either 
completely opaque or completely transparent. A solid design can be opaque at some 
points and transparent at others. In translucent designs, at least one point has an 
opacity that is intermediate between completely opaque and completely transparent. 

All designs are either colorless or colored. Drawing a colorless design uses a de- 
fault color specified by the medium's foreground design. This is done by drawing 
with (cl im: compose-in cl im:+foreground-ink+ cl im:+transparent-ink+). 

A variety of designs are available. See 

"Concepts of Drawing in Color in CLIM" 

"Indirect Ink in CLIM" 

"Flipping Ink in CLIM" 

"Concepts of Patterned Designs in CLIM" 

"Concepts of Translucent Ink in CLIM" 

"Complex Designs in CLIM" 
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Indirect Ink in CLIM 

Drawing with an indirect ink is the same as drawing another design named direct- 
ly. For example, clim:+foreground-ink+ is a design that draws the medium's fore- 
ground design. 

Indirect inks exist for the benefit of output recording. For example, one can draw 
with clim:+background-ink+, change to a different climrmedium-background, and 
replay the output record; the replayed output will come out with a new background 
color. If the current background is the color red, drawing with clim:+background- 
ink+ means to draw with the background, whatever it is. On the other hand, draw- 
ing with clim:+red+ means to draw with the color red, even if the background is 
later changed to green. 

You can change the foreground or background design at any time. This changes 
the contents of the drawing plane. The effect is as if everything on the drawing 
plane is erased, the background design is drawn all over the drawing plane, and 
then everything that was ever drawn (provided it was saved in the output history) 
is redrawn using the new foreground and background. 

If an infinite recursion is created using an indirect ink, an error is signalled when 
the recursion is created, when the design is used for drawing, or both. 

clim:+foreground-ink+ is the default value of the rink drawing option. 

In the current implementation, the foreground and background must be colors. 

Two indirect inks are defined: 

clim:+foreground-ink+ 

An indirect ink that uses the medium's foreground design. 

clim:+background-ink+ 

An indirect ink that uses the medium's background design. 



Flipping Ink in CLIM 

You can use a flipping ink to interchange occurrences of two colors. The purpose 
of flipping is to allow the use of "XOR hacks" for temporary changes to the dis- 
play. For example, CLIM uses clim:-i-flipping-ink+ when drawing highlighting box- 
es. 

In the present implementation, both designs must be colors. 

clim:make-flipping-ink designl design2 

Returns a design that interchanges occurrences of two designs. 

clim:+flipping-ink+ 

A flipping ink that flips clim:+foreground-ink+ and clim:+background- 
ink+. 



Concepts of Patterned Designs in CLIM 
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Patterned designs are non-uniform designs that have a certain regularity. These 
include patterns, stencils, tiled designs, and transformed designs. 

In the present implementation, patterned designs are not fully supported as a fore- 
ground or background, and the only patterned designs supported as the rink draw- 
ing option are tilings of patterns of clim:+background-ink+ (or 
clim:+transparent-ink+) and clim:+foreground-ink+. In Cloe there is an additional 
restriction that the X offset and Y offset of the tiling must be 8. 

Patterns and Stencils 

Patterning creates a bounded rectangular arrangement of designs, like a checker- 
board. Drawing a pattern draws a different design in each rectangular cell of the 
pattern. To create a pattern, use climrmake-pattern. To repeat a pattern so it fills 
the drawing plane, apply clim:make-rectangular-tile to a pattern. 

A stencil is a special kind of pattern that contains only opacities. The name 
"stencil" refers to their use with clim:compose-in and clim:compose-over. 

Tiling 

Tiling repeats a rectangular portion of a design throughout the drawing plane. 
This is most commonly used with patterns. Use clim:make-rectangular-tile to 
make a tiled design. 

Transforming Designs 

The functions climrtransform-region and climruntransform-region accept any de- 
sign as their second argument and apply a coordinate transformation to the design. 
The result is a design that might be freshly constructed or might be an existing 
object. 

Transforming a uniform design simply returns the argument. Transforming a 
composite, flipping, or indirect design applies the transformation to the component 
design(s). Transforming a pattern, tile, or output record design is described in the 
sections on those designs. 



Operators for Patterned Designs in CLIM 

climrmake-pattern array designs 

Creates a pattern design that has (array-dimension 2d-array 0) cells in 
the vertical direction and (array-dimension 2d-array 1) cells in the hori- 
zontal direction. 

clim:make-pattern-from-bitmap-file pathname &rest args &key (:type :xll) .-designs 
.■format &allow-other-keys 

Reads the bitmap file specified by pathname and creates a CLIM pattern 
object from it. 

climrmake-stencil array 

Make a pattern of opacities from a two-dimensional array. 
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clim:make-rectangular-tile design width height 

Creates a design that tiles the specified rectangular portion of design 
across the entire drawing plane. 



Concepts of Translucent Ink in CLIM 

Translucent ink supports the following drawing techniques: 

• Controlling opacity 

• Blending colors 

• Compositing 

Controlling Opacity 

Opacity controls how new output covers previous output. Intermediate opacity val- 
ues result in color blending so that the earlier picture shows through what is 
drawn on top of it. 

An opacity is a real number between and 1; is completely transparent, 1 is 
completely opaque, and fractions are translucent. The opacity of a design is the de- 
gree to which it hides the previous contents of the drawing plane when it is 
drawn. Opacity can vary from totally opaque to totally transparent. 

Use climrmake-opacity or climrmake-stencil to specify opacity. 

Note: Opacity values that are not either fully transparent or fully opaque are 
not currently fully supported. 

Color Blending 

Drawing a design that is not completely opaque at all points allows the previous 
contents of the drawing plane to show through. The simplest case is drawing a 
solid design. Where the design is opaque, it replaces the previous contents of the 
drawing plane. Where the design is transparent, it leaves the drawing plane un- 
changed. 

In the more general case of drawing a translucent design, the resulting color is a 
blend of the design's color and the previous color of the drawing plane. For pur- 
poses of color blending, the drawn design is called the foreground and the drawing 
plane is called the background. 

The function clim:compose-over performs a similar operation. It combines two de- 
signs to produce a design, rather than combining a design and the contents of the 
drawing plane to produce the new contents of the drawing plane. For purposes of 
color blending, the first argument to clim:compose-over is called the foreground 
and the second argument is called the background. 

Color blending is defined by an ideal function: F(r 1 ,g 1; b ? ,o 1; r 2 ,g 2 ,b 2 >° 2^ ^° ^ r 
3 ,g 3 ,b 3 ,o 3 ) that operates on the color and opacity at a single point. 

(r v g 1 ,b 1 ,0 1 ) are the foreground color and opacity. 
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(r 2 ,g 2 ,b 2 >o 2 ) are the background color and opacity. 

(r 3 ,g 3 ,b 3 ,o 3 ) are the resulting color and opacity. 

The color blending function is conceptually applied at every point in the drawing 
plane. 

The function F performs linear interpolation on all four components: 

o 3 = ° 1 + (1 - ° 1 ) * ° 2 

r 3 = (o 1 *r 1 + (1 - o ? J * o 2 * r 2 ) / o 3 

g 3 = (o 1 *g 1 + (1 - o r ) * o 2 * g 2 ) I o 3 

b 3 = (o j * 6 j + (1 - o j) * o 2 * b 2 ) / o 3 

Note that if o 3 is zero, these equations would divide zero by zero. In that case r 3 , 
g 3 , and b 3 are defined to be zero. 

CLIM requires that F be implemented exactly if o 1 is zero or one or if o 2 is zero. 
If o 1 is zero, the result is the background. If o 1 is one or o 2 is zero, the result is 
the foreground. For fractional opacity values, an implementation can deviate from 
the ideal color blending function either because the implementation has limited 
opacity resolution or because the implementation can compute a different color 
blending function much more quickly. 

If a medium's background design is not completely opaque at all points, the conse- 
quences are unspecified. Consequently, a drawing plane is always opaque and draw- 
ing can use simplified color blending that assumes o 2 - 1 an d o 3 = 1. However, 
clim:compose-over must handle a non-opaque background correctly. 

Note that these (r,g,b,o) quadruples of real numbers between and 1 are mathe- 
matical and an implementation need not store information in this form. Most im- 
plementations are expected to use a different representation. 

Compositing 

Compositing creates a design whose appearance at each point is a composite of the 
appearances of two other designs at that point. Three varieties of compositing are 
provided: composing over, composing in, and composing out. 

You can use clim:compose-over, clim:compose-in, or clim:compose-out to create 
CLIM composite designs. 

In the present implementation compositing is not fully supported. 



Operators for Translucent Ink in CLIM 

The following functions can be used to create an opacity object, and to compose a 
new ink from a color and an opacity. (The three composition operators can also be 
used to compose more complex designs.) 

The present implementation of CLIM only fully supports opacities that are either 
fully opaque or fully transparent. It uses stipples for translucent opacities, and 
composition of translucent opacities does not work well. 
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climrmake-opacity value Creates a member of class climropacity whose opaci- 
ty is value, which is a real number in the range from to 1 (inclusive), 
where is fully transparent and 1 is fully opaque. 

clim:+transparent-ink+ When you draw a design that has areas of 
clim:+transparent-ink+, the former background shows through in those 
areas. 

clim:opacity-value opacity Returns the value of opacity, which is a real number 
in the range from to 1 (inclusive). 

clim:compose-over designl design2 

Composes a design that is equivalent to designl drawn on top of design2. 
Drawing the resulting design produces the same visual appearance as 
drawing design2 and then drawing designl, but might be faster and 
might not allow the intermediate state to be visible on the screen. 

clim:compose-in designl design2 

Composes a design by using the color (or ink) of designl and clipping to 
the inside of design2 (that is, design2 specifies the mask to use for 
changing the shape of the design). 

clim:compose-out designl design2 

Composes a design by using the color (or ink) of designl and clipping to 
the outside of design2 (that is, design2 specifies the mask to use for 
changing the shape of the design). 



Complex Designs in CLIM 

Note that the designs described in this section are not supported as the rink draw- 
ing option in the present implementation, but you can use climrdraw-design to 
draw them. 

You can use clim:make-design-from-output-record to make a design that replays 
the output record when the design is drawn using climrdraw-design. 

clim:make-design-from-output-record record 

Makes a design that replays record when the design is drawn by 
climrdraw-design. 

Since designs are a generalization of regions that include color, any member of the 
class climrregion acts as a solid, colorless design. The design is opaque at points 
in the region and transparent elsewhere. See the section "Regions in CLIM". 



Achieving Different Drawing Effects in CLIM 

Here are some examples of how to achieve a variety of commonly used drawing 
effects: 

• Drawing in the foreground color 
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Use the default, or specify :ink cl im:+foreground-ink+ 

• Erasing 

Specify :ink cl im:+background-ink+ 

• Drawing in color 

Specify :ink clim:+green+, or :ink (cl im: make-col or-rgb 0.6 0.0 0.4) 

• Painting a gray or colored wash over a display 

Specify a translucent design as the ink, such as 

:ink (cl im: compose-in clim:+black+ (cl im:make-opacity 0.25)) 

:ink (cl im:compose-in clim:+red+ (cl im:make-opacity 0.1)) 

:ink (cl im:compose-in cl im:+foreground-ink+ (cl im:make-opacity 0.75)) 

The last example can be abbreviated as :ink (cl im: make-opacity 0.75). On a 
non-color, non-grayscale display this will probably turn into a stipple. 

• Drawing an opaque gray 

Specify :ink (cl im: make-gray-col or 0.25) to draw in a shade of gray indepen- 
dent of the window's foreground color. On a non-color, non-grayscale display this 
will probably turn into a stipple. 

• Drawing a faded but opaque version of the foreground color 

Specify :ink (cl im: compose-over (cl im:compose-in cl im:+foreground-ink+ 
(cl im: make-opacity 0.25)) cl im:+background-ink+) to draw at 25% of the normal 
contrast. 

This technique is not fully supported in the present implementation. The design 
will generally be displayed as a stippled pattern. 

• Drawing a stipple of little bricks 

Specify :ink bricks, where bricks is defined as 
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(cl im: make- rectangular-tile 








(cl im: make-pattern #2a((0 
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• Drawing a tiled pattern 

Specify :ink (cl im:make-rectangular-tile (cl im: make-pattern array colors)) 

• Drawing a pattern 

Use (cl im: draw-pattern* medium (cl im:make-pattern array colors) x y) 

Presentation Types in CLIM 



Concepts of CLIM Presentation Types 

User Interaction with Application Objects 

In object-oriented programming systems, applications are built around internal ob- 
jects that model something in the real world. For example, an application that 
models a university has objects representing students, professors, and courses. A 
CAD system for designing circuits has objects representing gates, resistors, and so 
on. A desktop publishing system has objects representing paragraphs, headings, 
and drawings. 

Users need to interact with the application objects. A CLIM user interface enables 
users to see a visual representation of the application objects, and to operate on 
them. The objects that appear on the screen are not the application objects them- 
selves; they are one step removed. The visual representation of an object is a 
stand-in for the application object itself, in the same sense that the word "cat" (or 
a picture of a cat) is a stand-in for a real cat. 

A fundamental part of designing a CLIM user interface is to specify how users 
will interact with the application objects. There are two directions of interaction: 
you must present application objects to the user as output, and you must accept 
input from the user that indicates application objects. This is done with two basic 
functions, climrpresent and climraccept, and some related functions. 
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Application 
Object 




Presentation 



Presentations 

CLIM directly couples the visual representation of an object with the object itself. 
CLIM maintains this association in a data structure called a presentation. A pre- 
sentation embodies three things: 

• The underlying application object 

• Its presentation type 

• Its visual representation 

Output with its Semantics Attached 

For example, a university application has a "student" application object. The user 
sees a visual representation of a student, which might be a textual representation, 
or a graphical representation (such as a form with name, address, student id 
number), or even an image of the face of the student. The presentation type of the 
student is "student"; that is, the semantic type of the object that appears on the 
screen is "student". Since the type of the object is known, CLIM knows which op- 
erations are appropriate to perform on it. For example, when a student is dis- 
played, it is possible to perform operations such as "send-tuition-bill" or "show- 
transcript". 

Input Context 

Presentations are the basis of many of the higher-level application-building tools, 
which use climraccept to get input and climrpresent to do output. A command 
that takes arguments as input states the presentation type of each argument. This 
sets up an input context, in which presentations of that type are sensitive (they are 
highlighted when the pointer passes over them). When the user gives the send- 
tuition-bill command, the input context is looking for a student, so any displayed 
students are sensitive. Presentations that have been output in previous user inter- 
actions retain their semantics. In other words, CLIM has recorded the fact that a 
student has been displayed, and has saved this information so that whenever the 
input context expects a student, all displayed students are sensitive. 
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Inheritance 

CLIM presentation types can be designed to use inheritance, just as CLOS classes 
do. For example, a university might need to model night-student, which is a sub- 
class of student. When the input context is looking for a student, night-students 
are sensitive because they are represented as a subtype of student. 

The set of presentation types forms a type lattice, an extension of the Common 
Lisp CLOS type lattice. When a new presentation type is defined as a subtype of 
another presentation type, it inherits all the attributes of the supertype except 
those explicitly overridden in the definition. 

Presentation Translators 

You can define presentation translators to make the user interface of your applica- 
tion more flexible. For example, suppose the input context is expecting a command. 
In this input context, all displayed commands are sensitive, so the user can point 
to one to execute it. However, suppose the user points to another kind of presented 
object, such as a student. In the absence of a presentation translator, the student 
is not sensitive because the user must enter a command and cannot enter anything 
else to this input context. 

In the presence of a presentation translator that translates from students to com- 
mands, however, the presented student would be sensitive. In one scenario, the 
presented student is highlighted, and the middle pointer button does "Show Tran- 
script" of that student. 

What The Application Programmer Does 

By the time you get to the point of designing the user interface, you have probably 
designed the rest of the application and know what the application objects are. At 
this point, you need to do the following: 

• Decide what types of application objects will be presented to the user as output 
and accepted from the user as input. 

• For each type of application object that the user will see, assign a corresponding 
presentation type. In many cases, this means simply using a predefined presen- 
tation type. In other cases, you need to define a new presentation type. Usually 
the presentation type is the same as the class of the application object. 

• Use the application-building tools to specify the windows, menus, commands, and 
other elements of the user interface. Most of these elements will use the presen- 
tation types of your objects. 



How to Specify a CLIM Presentation Type 

This section describes how to specify a CLIM presentation type. For a complete de- 
scription of CLIM presentation types, options, and parameters, see the section 
"Predefined Presentation Types in CLIM". 
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Several CLIM operators take presentation types as arguments. You specify them 
using a presentation type specifier. 

Most presentation type specifiers are also Common Lisp type specifiers. Not all 
presentation types are Common Lisp types (such as the climrboolean presentation 
type) and not all Common Lisp types are presentation types, but there is a lot of 
overlap. 

A presentation type specifier appears in one of the following three patterns: 

name 

(name parameters...) 

((name parameters...) options...) 

Each presentation type has a name, which is usually a symbol naming the presen- 
tation type. The name can also be a CLOS class object; this usage provides the 
support for anonymous CLOS classes. 

The first pattern, name, indicates a simple presentation type, which can be one of 
the predefined presentation types or a user-defined presentation type. 

Examples of the first pattern are: 

integer A predefined presentation type 

pathname A predefined presentation type 

boolean A predefined presentation type 

student A user-defined presentation type 

The second pattern, (name parameters...), supports parameterized presentation 
types, which are analogous to parameterized Common Lisp types. The parameters 
state a restriction on the presentation type, so a parameterized presentation type is 
a specialization, or a subset, of the presentation type of that name with no param- 
eters. 

Examples of the second pattern are: 

(integer 10) A parameterized type indicating an integer in the 

range of zero through ten. 

(string 25) A parameterized type indicating a string whose 

length is 25. 

(member ryes :no rmaybe) 

A parameterized type which can be one of the three 
given values, :yes, :no, and rmaybe. 

The third pattern, ((name parameters...) options...), enables you to additionally spec- 
ify options that affect the use or appearance of the presentation, but not its se- 
mantic meaning. The options are keyword/value pairs. The options are defined by 
the presentation type. All presentation types accept the rdescription option, which 
enables you to provide a string describing the presentation type. If provided, this 
option overrides the description specified in the clim:define-presentation-type 
form, and also overrides the clim:describe-presentation-type presentation method. 
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For example, you can use this form to specify an octal integer from to 10: 

((integer 10) :base 8) 

Some presentation type options may appear as an option in any presentation type 
specifier. Currently, the only such option is : description. 



Using CLIM Presentation Types for Output 

The reason for using presentations for program output is so that the objects pre- 
sented will be acceptable to input functions. Suppose, for example, you present an 
object, such as 5, as a TV channel. When a command that takes a TV channel as 
an argument is issued or when a presentation translation function is "looking for" 
such a thing, the system will make that object sensitive. Also, when a command 
that is looking for a different kind of object (such as a highway number), the ob- 
ject 5 is not sensitive, because that object represents a TV channel, not a highway 
number. 

A presentation includes not only the displayed representation itself, but also the 
object presented and its presentation type. When a presentation is output to a 
CLIM window, the object and presentation type are "remembered" — that is, the 
object and type of the display at a particular set of window coordinates are record- 
ed in the window's output history. Because this information remains available, pre- 
viously presented objects are themselves available for input to functions for accept- 
ing objects. 



CLIM Operators for Presenting Typed Output 

An application can use the following operators to produce output that will be asso- 
ciated with a given Lisp object and be declared to be of a specified presentation 
type. This output is saved in the window's output history as a presentation. 
Specifically, the presentation remembers the output that was performed (by saving 
the associated output record), the Lisp object associated with the output, and the 
presentation type specified at output time. The object can be any Lisp object. 

CLOS provides these top-level facilities for presenting output. climrwith-output-as- 
presentation is the most general operator, and climrpresent and climrpresent-to- 
string support common idioms. 

clim:with-output-as-presentation (stream object type &key .-modifier :single-box (:al- 
low-sensitive-inferiors t) .-parent .-record-type) &body body 
Gives separate access to the two aspects of climrpresent: recording the 
presentation and drawing the visual representation. This macro gener- 
ates a presentation from the output done in the body to the stream. The 
presentation's underlying object is object, and its presentation type is 
type. 

climrpresent object &optional (presentation-type (climrpresentation-type-of object),) 
&key (stream *standard-output*) (-.view (climrstream-default-view 

stream),) -.modifier -.acceptably (:for-context-type presentation-type) .single- 
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box :allow-sensitive-inferiors sensitive (:record-type 'climrstandard- 
presentation) Creates a presentation on the stream of the specified ob- 
ject, using the given type and view to determine visual appearance. The 
manner in which the object is displayed depends on the presentation type 
of the object; the display is done by the type's climrpresent method for 
the given view. 

clim:present-to-string object &optional (presentation-type (climrpresentation-type- 
of object),) &key (:view clim:+textual-view+) acceptably (:for-context-type 
presentation-type) .string .-index 

Presents an object into a string in such a way that it can subsequently 
be accepted as input by clim:accept-from-string. 



Additional Functions for Operating on Presentations in CLIM 

The following functions can be used to examine or modify presentations. 

climrpresentationp object Returns t if and only if object is of type 
climrpresentation. 

climrpresentation-object presentation 

Returns the application object represented by the presentation presenta- 
tion. You can use setf on climrpresentation-object to change the object 
associated with the presentation. 

clim:presentation-type presentation 

Returns the presentation type of the presentation presentation. You can 
use setf on clim:presentation-type to change the presentation type asso- 
ciated with the presentation. 

climrpresentation The protocol class that corresponds to a presentation. 

climrstandard-presentation The standard class used by CLIM to represent pre- 
sentations. 



Using CLIM Presentation Types for Input 

The primary means for getting input from the end user is climraccept. Characters 
typed in at the keyboard in response to a call to climraccept are parsed, and the 
application object they represent is returned to the calling function. (The parsing 
is done by the climraccept method for the presentation type.) Alternatively, if a 
presentation of the type specified by the climraccept call (or one of its subtypes) 
has previously been displayed, the user can click on it with the pointer and 
climraccept returns it directly (that is, no parsing of a textual representation is 
required). 

Examples: 
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(cl im:accept 'string) ==> 
Enter a string: abracadabra 
"abracadabra" 

(cl im:accept 'string) ==> 

Enter a string [default abracadabra]: abracadabra 

"abracadabra" 

In the first call to climraccept, "abracadabra" was typed at the keyboard. In the 
second call to climraccept, the user clicked on the keyboard-entered string of the 
first function. In both cases, the same (in the sense of eq) string object "abra- 
cadabra" was returned. 

Typically, not just any kind of object is acceptable as input. Only an object of the 
presentation type specified in the current climraccept function (or one of its sub- 
types) can be input. In other words, the climraccept function establishes the cur- 
rent input context. For example, if the call to climraccept specifies an integer pre- 
sentation type, only a typed-in or a displayed integer is acceptable. Numbers dis- 
played as integer presentations would, in this input context, be sensitive, but those 
displayed as part of some other kind of presentation, such as a file pathname, 
would not. Thus, climraccept controls the input context and thereby the sensitivity 
of displayed presentations. 

Clicking on a presentation of a type different from the input context may cause 
translation to an acceptable object, if there is an appropriate presentation transla- 
tor defined. For example, you could make a presentation of a file pathname trans- 
late to an integer — say, its length — if you want. It is very common to translate 
to a command that operates on a presented object. For more information on pre- 
sentation translators, see the section "Presentation Translators in CLIM". 

Typically, the range of acceptable input is restricted. How restricted it is, is strict- 
ly up to you, the programmer. Using compound presentation types like and and or, 
and other predefined or specially devised presentation types gives you a high de- 
gree of flexibility and control over the input context. 



CLIM Operators for Accepting Input 

CLIM provides the following top-level operators for accepting typed input. 

climrwith-input-context is the most general operator, and climraccept and 
climraccept-from-string support common idioms. 

Note that climraccept does not insert newlines. If you want each call to 
climraccept to appear on a new line, use terpri. 

climraccept type &rest accept-args &key (.stream *standard-input*) (:view 
(climrstream-default-view stream),) .-default (-.default-type type) (-history 
type) -.provide-default (-.prompt t) (-prompt-mode 'mormal) (-display-default 
prompt) .-query-identifier .-activation-gestures -.additional-activation-gestures 
-.delimiter-gestures -.additional-delimiter-gestures -.insert-default (ireplace- 
input t) (:active-p t) 
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Requests input of the type from the stream, climraccept returns two val- 
ues, the object and its presentation type, climraccept works by prompt- 
ing, then establishing an input context via climrwith-input-context, and 
then calling the climraccept CLIM presentation method for type and 
-.view. 

climraccept-from-string type string &key (:view climr+textual-view+) .-default (de- 
fault-type type) .-activation-gestures -.additional-activation-gestures -.delim- 
iter-gestures -.additional-delimiter-gestures (.start 0) send 
Reads a printed representation of an object of type type from string. This 
function is like climraccept, except that the input is taken from string, 
starting at .start and ending at send. This function is analogous to read- 
from-string. 

climrwith-input-context (type &key .-override) f&optional object-var type-var event- 
var options-var) form &body clauses 

Establishes an input context of type type, evaluates form in the new con- 
text, and (optionally) evaluate one of clauses. 

climr*input-context* The current input context, which describes the presenta- 
tion type(s) currently being input by CLIM. 

climrinput-context-type context-entry 

Given one element from climr*input-context*, context-entry, this returns 
the presentation type of the context entry. 



Predefined Presentation Types in CLIM 

This section documents predefined CLIM presentation types, presentation type op- 
tions, and parameters. For more information on how to use these presentation 
types, see the section "How to Specify a CLIM Presentation Type". 

Note that any presentation type with the same name as a Common Lisp type ac- 
cepts the same parameters as the Common Lisp type (and additional parameters in 
a few cases). 



Basic Presentation Types in CLIM 

Here are basic presentation types that correspond to the Common Lisp types hav- 
ing the same name. 



t Clim Presentation Type 

The supertype of all other presentation types. 

Note that the climraccept method for this type allows input only via the pointer; 
if the user types anything on the keyboard, the climraccept method just beeps. 
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null Clim Presentation Type 

The presentation type that represents "nothing". The single object associated with 
this type is nil, and its printed representation is "None". 



climrboolean Clim Presentation Type 

The presentation type that represents t or nil. The textual representation is "Yes" 
and "No", respectively. 



symbol Clim Presentation Type 

The presentation type that represents a symbol. 

keyword Clim Presentation Type 

The presentation type that represents a symbol in the keyword package. It is a 
subtype of symbol. 

Numeric Presentation Types in CLIM 

The following presentation types represent the Common Lisp numeric types having 
the same names. 

number Clim Presentation Type 

The presentation type that represents a general number. It is the supertype of all 
the number types. 

complex &optional type Clim Presentation Type 

The presentation type that represents a complex number. It is a subtype of 
number. 

type is the type to use for the components. It must be a subtype of real. 

future-common-lisprreal &optional low high Clim Presentation Type 

The presentation type that represents either a ratio, an integer, or a floating point 
number between low and high, low and high can be inclusive or exclusive, as in 
Common Lisp type specifiers. 

Options to this type are :base and rradix, which are the same as for the integer 
type. This type is a subtype of number. 

rational &optional low high Clim Presentation Type 
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The presentation type that represents either a ratio or an integer between low and 
high. Options to this type are :base and rradix, which are the same as for the 
integer type. It is a subtype of real. 



integer &optional low high Clim Presentation Type 

The presentation type that represents an integer between low and high. Options to 
this type are :base (default 10) and rradix (default nil), which correspond to 
*print-base* and *print-radix*, respectively. It is a subtype of rational. 



ratio &optional low high Clim Presentation Type 

The presentation type that represents a ratio between low and high. Options to 
this type are rbase and rradix, which are the same as for the integer type. It is a 
subtype of rational. 



float &optional low high Clim Presentation Type 

The presentation type that represents a floating point number between low and 
high. This type is a subtype of climrreal. 



Character and String Presentation Types in CLIM 

These two presentation types can be used for reading and writing character and 
strings. 



character Clim Presentation Type 

The presentation type that represents a Common Lisp character object. 

string &optional length Clim Presentation Type 

The presentation type that represents a string. If length is specified, the string 
must have exactly that many characters. 

Pathname Presentation Type in CLIM 

clim-lisprpathname Clim Presentation Type 

The presentation type that represents a pathname. 

The options are rdefault-type (which defaults to nil), r default- version (which de- 
faults to mewest), and rmerge-default (which defaults to t). If rmerge-default is 
nil, climraccept returns the exact pathname that was entered, otherwise 
climraccept merges against the default provided to climraccept and rdefault-type 
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and : default- version, using merge-pathnames. If no default is specified, it de- 
faults to *default-pathname-defaults*. 



One-of and Some-of Presentation Types in CLIM 

The "one-of" and "some-of" presentation types can be used to accept and present 
one or more items from a set of items. The set of items can be specified as a 
"rest" argument, a sequence, or an alist. 

This table summarizes single ("one-of") and multiple ("some-of") selection presen- 
tation types. Each row represents a type of presentation. Columns contain the asso- 
ciated single and multiple selection presentation types. 

Args Single Multiple 

most general climrcompletion climrsubset-completion 

&rest elements member climrsubset 

sequence climrmember-sequence climrsubset-sequence 

alist clim:member-alist clim:subset-alist 

climrcompletion sequence &key :test :value-key Clim Presentation Type 

The presentation type that selects one from a finite set of possibilities, with 
"completion" of partial inputs. Several types are implemented in terms of the 
climrcompletion type, including climrtoken-or-type, climrnull-or-type, member, 
climrmember-sequence, and climrmember-alist. 

The presentation type parameters are: 

sequence A list or vector whose elements are the possibilities. Each possibili- 
ty has a printed representation, called its name, and an internal 
representation, called its value, climraccept reads a name and re- 
turns a value, climrpresent is given a value and outputs a name. 

-.test A function that compares two values for equality. The default is 

eql. 

:value-key A function that returns a value given an element of sequence. The 
default is identity. 

The following presentation type options are available: 

mame-key 

A function that returns a name, as a string, given an element of se- 
quence. The default is a function that behaves as follows: 
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Argument 


Returned Value 


string 


the string 


null 


the string "NIL" 


cons 


string of the car 


symbol 


string-capitalize of its name 


otherwise 


princ-to-string of it 



: documentation-key 

A function that returns nil or a descriptive string, given an element 
of sequence. The default always returns nil. 

rpartial-completers 

A (possibly empty) list of characters that delimit portions of a name 
that can be completed separately. The default is a list of one char- 
acter, ttsSpace. 



member &rest elements Clim Presentation Type Abbreviation 

The presentation type that specifies one of elements. The options (:name-key, 
rvalue-key, and rpartial-completers) are the same as for climrcompletion. 



climrmember-sequence sequence &key :test Clim Presentation Type Abbreviation 

Like member, except that the set of possibilities is the sequence sequence. The pa- 
rameter :test and the options (mame-key, rvalue-key, and rpartial-completers) are 
the same as for climrcompletion. 



climrmember-alist alist &key :test Clim Presentation Type Abbreviation 

Like member, except that the set of possibilities is the alist alist. Each element of 
alist is either an atom (as in climrmember-sequence) or a list whose car is the 
name of that possibility and whose cdr is one of the following: 

• The value (which must not be a cons) 

• A list of one element, the value 

• A property list containing one or more of the following properties: 

rvalue — the value 

r documentation — a descriptive string 

The :test parameter and the options are the same as for climrcompletion except 
that the rvalue-key and r documentation-key options default to functions that sup- 
port the specified alist format. 



climrsubset-completion sequence &key :test :value-key Clim Presentation Type 
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The presentation type that selects one or more from a finite set of possibilities, 
with completion of partial inputs. The parameters and options are the same as for 
climrcompletion with the following additional options: 

rseparator The character that separates members of the set of possibili- 
ties in the printed representation when there is more than one. 
The default is comma. 

:echo-space (t or nil) Whether to insert a space automatically after the 
separator. The default is t. 

The other subset types (climrsubset, climrsubset-sequence, and clim:subset-alist) 
are implemented in terms of the climrsubset-completion type. 



climrsubset &rest elements Clim Presentation Type Abbreviation 

The presentation type that specifies a subset of elements. Values of this type are 
lists of zero or more values chosen from the possibilities in elements. The printed 
representation is the names of the elements separated by the separator character. 
The options (:name-key, rvalue-key, rpartial-completers, rseparator, and recho- 
space) are the same as for climrsubset-completion. 



climrsubset-sequence sequence &key :test Clim Presentation Type Abbreviation 

Like climrsubset, except that the set of possibilities is the sequence sequence. The 
parameter :test and the options (mame-key, rvalue-key, rpartial-completers, 
rseparator, and recho-space) are the same as for climrsubset-completion. 



climrsubset-alist alist &key :test Clim Presentation Type Abbreviation 

Like climrsubset, except that the set of possibilities is the alist alist. The parame- 
ter :test and the options (mame-key, rvalue-key, rpartial-completers, rseparator, 
and recho-space) are the same as for climrsubset-completion. The parameter alist 
has the same format as climrmember-alist. 



Sequence Presentation Types in CLIM 

The following two presentation types can be used to accept and present a sequence 
of objects. 



sequence type Clim Presentation Type 

The presentation type that represents a sequence of elements of type type. The 
printed representation of a sequence type is the elements separated by the separa- 
tor character. It is unspecified whether climraccept returns a list or a vector. You 
can specify the following options: 
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rseparator The character that separates members of the set of possibili- 
ties in the printed representation when there is more than one. 
The default is comma (#\,). 

:echo-space If this is t, then CLIM will insert a space automatically after 
the separator, otherwise it will not. The default is t. 

type can be a presentation type abbreviation. 



climrsequence-enumerated &rest types Clim Presentation Type 

climrsequence-enumerated is like sequence, except that the type of each element 
in the sequence is individually specified. It is unspecified whether climraccept re- 
turns a list or a vector. You can specify the following options: 

rseparator The character that separates members of the set of possibili- 
ties in the printed representation when there is more than one. 
The default is comma (tt\, ). 

recho-space If this is t, then CLIM will insert a space automatically after 
the separator, otherwise it will not. The default is t. 

The elements of types can be presentation type abbreviations. 
Meta Presentation Types in CLIM 

or &rest types Clim Presentation Type 

The presentation type that is used to specify one of several types, for example, 

(or (member : al 1 :none) integer) 

climraccept returns one of the possible types as its second value, not the original 
or presentation type specifier. 

The elements of types can be presentation type abbreviations. 

The climraccept method for the or type works by iteratively calling climraccept 
on each of the presentation types in types. It establishes a condition handler for 
userrrparse-error, calls climraccept, and returns the result if no condition is sig- 
nalled. If a userrrparse-error condition is signalled, CLIM calls the climraccept 
method for the next type. If all of the calls to climraccept fail, the climraccept 
method for or signals a userrrparse-error. 

and &rest types Clim Presentation Type 

The presentation type that is used for multiple inheritance, and is usually used in 
conjunction with satisfies. For example, 

(and integer (satisfies oddp)) 
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The elements of types can be presentation type abbreviations. 

The first type in types is in charge of accepting and presenting. The remaining el- 
ements of types are used for type checking (for example, filtering applicability of 
presentation translators). 

The and type has special syntax that supports the two "predicates" satisfies and 
not. satisfies and not cannot stand alone as presentation types and cannot be first 
in types, not can surround either satisfies or a presentation type. 



Compound Presentation Types in CLIM 

The following compound presentation types are provided because they implement 
some common idioms. 



clim:token-or-type tokens type Clim Presentation Type Abbreviation 

A compound type that is used to select one of a set of special tokens, or an object 
of type type, tokens is anything that can be used as the alist parameter to 
clim:member-alist; typically it is a list of keyword symbols. 

type can be a presentation type abbreviation. 

For example, the following is a common way of using clim:token-or-type: 

(cl im:accept ' (cl im: token-or-type (:all :none) integer) 
: prompt "How many?") 



clim:null-or-type type Clim Presentation Type Abbreviation 

A compound type that is used to select nil, whose printed representation is the 
special token "None", or an object of type type. 

type can be a presentation type abbreviation. 



clim:type-or-string type Clim Presentation Type Abbreviation 

A compound type that is used to select an object of type type or an arbitrary 
string, for example, (clim:type-or-string integer). Any input that climraccept can- 
not parse as the representation of an object of type type is returned as a string. 

type can be a presentation type abbreviation. 



Command and Form Presentation Types in CLIM 

The command and form presentation types are complex types provided primarily 
for use by the top level interactor of an application. 
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climrexpression Clim Presentation Type 

The presentation type used to represent any Lisp object. The textual view of this 
type looks like what the standard prinl and read functions produce and accept. 

This type has one option, :auto-activate, which controls whether the expression 
terminates on a delimiter gestures, or when the Lisp expression "balances" (for 
example, you type enough close parentheses to complete the expression). The de- 
fault for :auto-activate is nil, meaning that the user must use an activation ges- 
ture to terminate the input. 



climrform Clim Presentation Type 

The presentation type used to represent a Lisp form. This type is a subtype of 
climrexpression. It has one option, rauto-activate, which is treated the same way 
as the rauto-activate option to climrexpression. 



climrcommand &key : command-table Clim Presentation Type 

The presentation type used to represent a CLIM command processor command and 
its arguments. : command-table can be either a command table or a symbol that 
names a command table. 

If : command-table is not supplied, it defaults to the command table for the current 
application, that is, (climrframe-command-table climr*application-frame*). 

When you call climraccept on this presentation type, the returned value is a list; 
the first element is the command name, and the remaining elements are the com- 
mand arguments. You can use climrcommand-name and climrcommand- 
arguments to access the name and arguments of the command object. 

For more information about CLIM command objects, see the section "Command 
Objects in CLIM". 



climrcommand-name cfekey : command-table Clim Presentation Type 

The presentation type used to represent the name of a CLIM command processor 
command in the command table : command-table. 

: command-table may be either a command table or a symbol that names a com- 
mand table. If : command-table is not supplied, it defaults to the command table for 
the current application. The textual representation of a climrcommand-name ob- 
ject is the command-line name of the command, while the internal representation 
is the command name. 



climrcommand-or-form &key : command-table Clim Presentation Type 

The presentation type used to represent either a Lisp form or a CLIM command 
processor command and its arguments. In order for the user to indicate that he 
wishes to enter a command, a command dispatch character must be typed as the 
first character of the command line. 
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See the variable clim:*command-dispatchers*. 

: command-table may be either a command table or a symbol that names a com- 
mand table. If : command-table is not supplied, it defaults to the command table for 
the current application, that is, (clim:frame-command-table clim:*application- 
frame*). 



Defining a New Presentation Type in CLIM 



Concept of Defining a New Presentation Type in CLIM 

CLIM's standard set of presentation types will be useful in many cases, but most 
applications will need customized presentation types to represent the objects mod- 
eled in the application. 

By defining a presentation type, you define all of the user interface components of 
the entity: 

• A displayed representation, for example, textual or graphical 

• A textual representation, for user input via the keyboard (a textual rep- 
resentation is optional) 

• Pointer sensitivity, for user input via the pointer 

In other words, by defining a presentation type, you describe in one place all the 
information about an object necessary to display it to the user and interact with 
the user for getting input. 

The set of presentation types forms a type lattice, an extension of the Common 
Lisp CLOS type lattice. When a new presentation type is defined as a subtype of 
another presentation type, it inherits all the attributes of the supertype except 
those explicitly overridden in the definition. 

To define a new presentation type, you follow these steps: 

1. Use the clim:define-presentation-type macro. 

• Name the new presentation type. 

• Supply parameters that further restrict the type (if appropriate). 

• Supply options that affect the appearance of the type (if appropriate). 

• State the supertypes of this type, to make use of inheritance (if appropri- 
ate). 

2. Define CLIM presentation methods. 

• Specify how objects are displayed with a climrpresent presentation method. 
(You must define a climrpresent method, unless the new presentation type 
inherits a method that is appropriate for it.) 



Page 1307 



Specify how objects are parsed with a climraccept presentation method. (In 
most cases, you must define a climraccept method, unless the new presen- 
tation type inherits a method that is appropriate for it. If it is never neces- 
sary to enter the object by typing its representation on the keyboard, you 
don't need to provide this method.) 

Specify the type/subtype relationships of this type and its related types, if 
necessary, with climrpresentation-typep and climrpresentation-subtypep 

presentation methods. (You must define or inherit these methods when 
defining a presentation type that has parameters.) 



CLIM Presentation Type Inheritance 

Every presentation type is associated with a CLOS class. In the common case, the 
name of the presentation type is a class object or the name of a class, and that 
class is not a clos:built-in-class. In this case, the presentation type is the same as 
the CLOS class. 

When the class is a subclass of clos:built-in-class, the presentation type is a built 
on a special class that is internal to CLIM. This class is not named name, since 
that could interfere with built-in Common Lisp types such as and, member, and 
integer. clos:class-name of this class returns a list (clim:presentation-type 

name). 

IMPORTANT NOTE: If the same name is defined with both closrdefclass (or 

defstruct) and clim:define-presentation-type, the 
closrdefclass (or defstruct) must be done first. 

Every CLOS class (except for built-in classes) is a presentation type, as is its 
name. If it has not been defined with clim:define-presentation-type, it allows no 
parameters and no options. 

As in CLOS, inheriting from a built-in class does not work, unless you specify the 
same inheritance that the built-in class already has; you may want to do this in 
order to add presentation type parameters to a built-in class. 

If you define a presentation type that does not have the same name as a CLOS 
class, you must define a climrpresentation-typep presentation method for it. If 
you define a presentation type that has parameters, you must define or inherit a 
climrpresentation-subtypep for it. 

If your presentation type has the same name as a class, doesn't have any parame- 
ters or options, doesn't have a history, and doesn't need a special description, you 
do not need to call climrdefine-presentation-type. 

During method combination, presentation type inheritance is used both to inherit 
methods ("what parser should be used for this type?"), and to establish the seman- 
tics for the type ("what objects are sensitive in this context?"). Inheritance of 
methods is the same as in CLOS and thus depends only on the type name, not on 
the parameters and options. 
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Presentation type inheritance translates the parameters of the subtype into a new 
set of parameters for the supertype, and translates the options of the subtype into 
a new set of options for the supertype. 



Example of Defining a New CLIM Presentation Type 

This example shows how to define a new presentation type, and how to define the 
presentation methods for the new type. First we define the application objects 
themselves and create some test data. Then we define a simple presentation type, 
and gradually add enhancements to it to show different CLIM techniques. 

This example models a university. The application objects are students, courses, 
and departments. This is such a simple example that there is no need to use in- 
heritance. 

Note that this example must be run in a package, such as clim-user, that has ac- 
cess to symbols from the clim and clos packages. 

These are the definitions of the application objects: 

(def class student () 

((name : reader student-name :initarg :name) 
(courses :accessor student-courses :initform nil))) 

(def class course () 

((name : reader course-title :initarg :title) 
(department : reader course-department :initarg : department))) 

(def class department () 

((name : reader department-name :initarg :name))) 

The following code provides support for looking up objects by name. 

(defvar xstudent-tablex (make-hash-table :test #' equal)) 
(defvar xcourse-tablex (make-hash-table :test #' equal)) 
(defvar xdepartment-tablex (make-hash-table :test #' equal)) 

(defun find-student (name &optional (errorp t)) 
(or (gethash name xstudent-tablex) 

(and errorp (error "There is no student named ~S" name)))) 

(defun find-course (name &optional (errorp t)) 
(or (gethash name xcourse-tablex) 

(and errorp (error "There is no course named ~S" name)))) 

(defun find-department (name &optional (errorp t)) 
(or (gethash name xdepartment-tablex) 

(and errorp (error "There is no department named ~S" name)))) 
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(defmethod initial ize-instance :after ((student student) &key) 
(setf (gethash (student-name student) xstudent-tablex) student)) 

(defmethod initial ize-instance :after ((course course) &key) 
(setf (gethash (course-title course) xcourse-tablex) course)) 

(defmethod initial ize-instance : after ((department department) &key) 

(setf (gethash (department-name department) xdepartment-tablex) department)) 

(defmethod print-object ((student student) stream) 
(print-unreadable-object (student stream :type t) 
(write-string (student-name student) stream))) 

(defmethod print-object ((course course) stream) 
(print-unreadable-object (course stream :type t) 

(write-string (course-title course) stream)) 
(format stream " (~A) " (department-name (course-department course)))) 

(defmethod print-object ((department department) stream) 
(print-unreadable-object (department stream :type t) 
(write-string (department-name department) stream))) 

Here we create some test data: 

(flet ((make-student (name &rest courses) 

(setf (student-courses (make-instance 'student :name name)) 
(copy-list courses))) 
(make-course (title department) 

(make-instance 'course :title title :department department)) 
(make-department (name) 

(make-instance 'department :name name))) 
(let* ((english (make-department "English")) 
(physics (make-department "Physics")) 
(agriculture (make-department "Agriculture")) 
(englit (make-course "English Literature" english)) 
(mabinogion (make-course "Deconstructing the Mabinogion" english)) 
(e&m (make-course "Electricity and Magnetism II" physics)) 
(beans (make-course "The Cultivation and Uses of Beans" agriculture)) 
(horses (make-course "Horse Breeding for Track and Field" agriculture)) 
(corn (make-course "Introduction to Hybrid Corn" agriculture))) 
(make-student "Susan Charnas" englit e&m) 
(make-student "Orson Card" englit beans) 
(make-student "Roberta MacAvoy" horses mabinogion) 
(make-student "Philip Farmer" corn beans horses))) 
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You can evaluate the following forms to test what you have done so far. A printed 
representation of each object will be displayed. 

(find-student "Philip Farmer") 
=>#<STUDENT Philip Farmer> 

(find-course "The Cultivation and Uses of Beans") 
=>#<C0URSE The Cultivation and Uses of Beans (Agricul ture)> 

(find-department "Agriculture") 
=>#<DEPARTMENT Agriculture 

If you try to evaluate a form that has not yet been defined (for example, if you try 
to look up a student that "doesn't exist"), you might see something like this: 

Connand: (find-student "Jill Parker") 

Error: There is no student naned "Jill Parker" 

FIND-STUDENT 

Rrg (NRME) : "Jill Parker" 

— Be f suited s.rgs : — 

Rrg 1 (ERRORP) : T 
s-R^ <fieqrt> ; Return to Breakpoint ZMRCS in Editor Typeout Window 1 

s-B: Editor Top Level 

s-C: Restart process Znacs Windows 



Now we are ready to develop a user interface. This first example defines presenta- 
tions of students, represented by their names. This simple presentation type does 
not provide parameters or options. A real program would also provide presentation 
types for courses and departments, but this example shows students only. 

(cl im:def ine-presentati on-type student ()) 

(cl im:def ine-presen tat ion-method cl im: present 

(student (type student) stream 
(view cl im: textual-view) &key) 
(write-string (student-name student) stream)) 

(cl im:def ine-presen tat ion-method cl im: accept 

((type student) stream 
(view cl im: textual-view) &key) 
(let* ((token (cl im: read-token stream)) 

(student (find-student token nil))) 
(when student 

(return-from dim: accept student)) 
(cl im: input-not-of-requi red-type token type))) 

Test this by evaluating the following forms in a CLIM Lisp Listener. Note that 
there is no completion and find-student is case-sensitive, so the student's name 
must be entered exactly to be accepted. 
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(cl im:describe-presentati on-type 'student xstandard-outputx) 
(cl im:describe-presentati on-type 'student xstandard-outputx 5) 
(cl im: present (find-student "Philip Farmer") 'student) 
(cl im:accept 'student :default (find-student "Philip Farmer")) 

We can improve the input interface by using completion over elements of *stu- 
dent-table*. 

(cl im:def ine-presen tat ion-method cl im: accept 

((type student) stream 
(view textual -view) &key) 
(values ; suppress values after the first 

(cl im:completing-f rom-suggestions 

(stream : partial -completers '(#\space)) 
;; SUGGEST takes arg of name, object 
(maphash #'cl im:suggest xstudent-tablex)))) 

Test this by evaluating the following form in a CLIM Lisp Listener. 

(clim:accept 'student :default (find-student "Philip Farmer")) 

Try the Help key, and try entering just the initials of a student, separated by a 
space; they complete to the full name. 

It would be useful to be able to select students in a particular department. We can 
revise the presentation type for student by adding a parameter for the depart- 
ment. A student is in a department if the student is taking any course in that de- 
partment. 

(defun student-in-department-p (student department) 

(find department (student-courses student) :key tf'course-department)) 

(cl im:def ine-presentati on-type student (&optional department)) 

When a presentation type has parameters, the defaults for the climrpresentation- 
typep and climrpresentation-subtypep presentation methods are not sufficient. 
Therefore, we need to define these presentation methods. We also define a new 
clim:describe-presentation-type method. 

(cl im:def ine-presen tat ion-method cl im:presentation-typep 

(object (type student)) 
(or (eq department '*) 

(student-in-department-p object department))) 
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(cl im:def ine-presen tat ion-method cl im:presentation-subtypep 

((typel student) type2) 
(let ((departmentl (cl im:with-presentation-type-parameters 

(student typel) department)) 
(department2 (cl im:with-presentat ion- type-parameters 
(student type2) department))) 
(values (or (eq departmentl department2) 
(eq department2 '*)) 
t))) 

(cl im:def ine-presen tat ion-method cl im:describe-presen tat ion- type 

((type student) stream plural -count) 
(when (eql plural -count 1) 

(write-string (if (or (eq department '*) 

(not (find (char (department-name department) 0) "aeiou" 
:test tf'char-equal ))) 
"a " 
" an " ) 
stream)) 
(format stream 

(if (and (integerp plural-count) (> plural-count 1)) 

(if (eq department '*) "~R student" :P" "~R ~A student" :*~:P") 
(if (eq department '*) "student~P" "~x~A student" :*~:P")) 
(typecase plural -count 
(integer plural-count) 
(null 1) 
(otherwise 2)) 
(unless (eq department '*) 

(department-name department)))) 

Evaluate the following forms to test these methods: 

(cl im:presentation-typep (find-student "Philip Farmer") 

'(student , (find-department "Agriculture"))) 

(cl im:presentation-typep (find-student "Philip Farmer") 

'(student , (find-department "English"))) 

(cl im:presentation-typep "Philip Farmer" 

'(student , (find-department "Agriculture"))) 

(cl im:presentation-subtypep '(student , (find-department "Agriculture")) 

' (student *)) 

(cl im:presentation-subtypep '(student , (find-department "Agriculture")) 

'(student , (find-department "English"))) 
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(cl im:describe-presentati on-type '(student , (find-department "Physics"))) 
(cl im:describe-presentation-type '(student *)) 

The existing method for climraccept suggests all the students, even the ones in 
the wrong department, so we provide the following raround method to check that 
we are returning a student in the right department. 

(cl im:def ine-presentation-method clim:accept :around 

((type student) stream view &key) 
(declare (ignore stream view)) 
(multiple-value-bind (object actual-type) 
(cal 1 -next-method) 
(unless (cl im:presentation-typep object type) 

(cl im: input-not-of-requi red-type object type)) 
(values object actual -type))) 

Evaluate the following form in a CLIM Lisp Listener before and after defining the 
above method. 

(clim:accept '(student , (find-department "Agriculture"))) 

Type the following at the prompt: 

susan RETURN 

Before defining the above method, climraccept returns a student that is not in the 
specified department. After defining the above method, CLIM asks the user to try 
again. But if you press HELP, Susan Charnas is still listed as one of the possibili- 
ties. 

Another way to do this would be to filter out students in other departments before 
calling climrsuggest. To do that, define this method instead of the preceding 
method. This way works better because the completion possibilities won't include 
any extra students. 

(cl im:def ine-presentation-method cl im: accept 

((type student) stream 
(view cl im: textual-view) &key) 
(values ; suppress values after the first 

(cl im:completing-f rom-suggestions 

(stream : partial -completers '(#\space)) 
(maphash (if (eq department '*) 
#'cl im:suggest 
if (lambda (name student) 

(when (student-in-department-p student department) 
(cl im: suggest name student)))) 
xstudent-tabl e*) ) ) ) 

On Genera, this gets rid of the raround method that we don't want any more. (On 
other platforms, you can use closrremove-method.) 
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(scl : fundef ine ' (clos: method cl im:accept-method (student t t t t t) :around)) 

Evaluate these forms in the CLIM Lisp Listener again. Try entering the names of 
agricultural and non-agricultural students. 

(cl im:accept '(student , (find-department "Agriculture"))) 
(clim:accept 'student) 

You can also try the HELP key. 

It is easy to define an abbreviation for a presentation type. Here we define aggie 
as an abbreviation for a student in the Agriculture department: 

(cl im:def ine-presentati on-type-abbreviation aggie () 
'(student , (find-department "Agriculture"))) 

Evaluate these forms to test it. 

(cl im:describe-presen tat ion- type 'aggie) 
(clim:accept 'aggie) 

Now we refine our example by providing an option that controls the printing of 
the student's name. 

(cl im:def ine-presentati on-type student (&optional department) 
:options (last-name-first)) 

(cl im:def ine-presen tat ion-method cl im: present 

(student (type student) stream 
(view cl im: textual-view) &key) 
(let* ((name (student-name student)) 

(index (and last-name-first (position #\space name :from-end t)))) 
(cond ((null index) 

(write-string name stream)) 
(t 
(write-string name stream :start (1+ index)) 
(write-string ", " stream) 
(write-string name stream :end index))))) 
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(cl im:def ine-presen tat ion-method cl im: accept 

((type student) stream 
(view cl im: textual-view) &key) 
(values ; suppress values after the first 

(cl im:completing-f rom-suggestions 

(stream : partial -completers ' (#\space #\,)) 
(maphash #' (lambda (name student) 

(when (cl im:presentation-typep student type) 
(cl im:suggest 

(or (and last-name-first 

(let ((index (position #\space name 

:from-end t))) 
(and index 

(concatenate 'string 

(subseq name (1+ index)) 

(subseq name index))))) 
name) 
student))) 
xstudent-tabl ex) ) ) ) 

Evaluate these forms to test it. 

(cl im:present (find-student "Philip Farmer") 'student) 

(cl im:present (find-student "Philip Farmer") '((student) : last-name-f i rst t)) 

(dim: accept '((student) : last-name-f i rst t)) 

(clim:accept '((student , (find-department "Physics")) : last-name-f i rst t)) 

Since presentation type options are not automatically inherited by subtypes and 
abbreviations, the following example doesn't work. 

(clim:accept '((aggie) : last-name-f i rst t)) 

This example works if you redefine aggie to accept the :last-name-first option: 

(cl im:def ine-presentati on-type-abbreviation aggie () 
'((student , (find-department "Agriculture")) 

: 1 ast-name-f i rst , 1 ast-name-f i rst) 
:options (last-name-first)) 

You can override the presentation type's description: 

(clim:accept '((student , (find-department "English")) 
description "English major")) 



CLIM Operators for Defining New Presentation Types 
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clim:define-presentation-type name parameters &key .-options dnherit-from -.descrip- 
tion -.history :parameters-are-types 
Defines a CLIM presentation type. 

climrdefine-presentation-method presentation-function-name [qualifiers]* special- 
ized-lambda-list &body body 

Defines a presentation method for the function named presentation- 
function-name on the presentation type named in specialized-lambda-list. 

For the names and lambda-lists of CLIM presentation methods, see the section 
"Presentation Methods in CLIM". 

Under rare circumstances, you may wish to define or call a new presentation 
generic function. The following forms may be used to accomplish this. 

climrdefine-presentation-generic-function generic-function-name presentation- 
function-name lambda-list &rest options 

Defines a new presentation named presentation-function-name whose 
methods are named by generic- function-name, lambda-list and options are 
as for closrdefgeneric. 

climrdefine-default-presentation-method presentation-function-name [qualifiers]* 
specialized-lambda-list &body body 

This is like climrdefine-presentation-method, except that it is used to 
define a default method that will be used if there are no more specific 
methods. 

climrfuncall-presentation-generic-function presentation-function-name &body argu- 
ments 

Funcalls the presentation generic function presentation-function-name 
with arguments arguments using funcall. 

climrapply-presentation-generic-function presentation-function-name &body argu- 
ments 

Applies the presentation generic function presentation-function-name to 
arguments arguments using apply. 



CLIM Operators for Defining Presentation Type Abbreviations 

You can define an abbreviation for a presentation type for the purpose of naming a 
commonly used cliche. The abbreviation is simply another name for a presentation 
type specifier. 

clim:define-presentation-type-abbreviation name parameters expansion &key op- 
tions 

Defines a presentation type that is an abbreviation for the presentation 
type specifier that is the value of expansion. 

This example defines a presentation type to read an octal integer: 
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(cl im:def ine-presen tat ion- type-abb rev i at ion octal -integer 

(&optional low high) 
'((integer ,low ,high) :base 8 :description "octal integer")) 

When writing presentation type abbreviations, it is sometimes useful to let CLIM 
include or exclude defaults for parameters and options. In some cases, you may al- 
so find it necessary to "expand" a presentation type abbreviation. The following 
three functions are useful in these circumstances. 

clim:expand-presentation-type-abbreviation type &optional environment 

clim:expand-presentation-type-abbreviation is like climrexpand- 

presentation-type-abbreviation-1, except that type is repeatedly expand- 
ed until all presentation type abbreviations have been expanded. 

clim:expand-presentation-type-abbreviation-l type &optional environment 

If the presentation type specifier type is a presentation type abbreviation, 
or is an and, or, sequence, or climrsequence-enumerated that contains 
a presentation type abbreviation, then clim:expand-presentation-type- 
abbreviation-1 expands the type abbreviation once, and returns two val- 
ues, the expansion and t. If type is not a presentation type abbreviation, 
then the values type and nil are returned. 

clim:make-presentation-type-specifier type-name-and-parameters &rest options 

Given a presentation type name and its parameters type-name-and- 
parameters and some presentation type options, make a new presentation 
type specifier that includes all of the type parameters and options. 



Presentation Methods in CLIM 

You define presentation methods using climrdefine-presentation-method. 

climrdefine-presentation-method presentation-function-name [qualifiers]* special- 
ized-lambda-list &body body 

Defines a presentation method for the function named presentation- 
function-name on the presentation type named in specialized-lambda-list. 

All presentation methods have an argument named type that must be specialized 
with the name of a presentation type. The value of type is a presentation type 
specifier, which can be for a subtype that inherited the method. 

All presentation methods except those for climrpresentation-subtypep have lexical 
access to the parameters from the presentation type specifier. Presentation meth- 
ods for the functions climraccept, climrpresent, clim:describe-presentation-type, 
clim:presentation-type-specifier-p, and climraccept-present-default also have lexi- 
cal access to the options from the presentation type specifier. 

Presentation methods inherit and combine in the same way as ordinary CLOS 
methods. The reason presentation methods are not exactly the same as ordinary 
CLOS methods revolves around the type argument. The parameter specializer for 
type is handled in a special way and presentation method inheritance arranges the 
type parameters and options seen by each method. 
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Here are the names of the various presentation methods defined by climrdefine- 
presentation-method , along with the lambda-list for each method. For a complete 
description of these presentation methods,see the section "Dictionary of CLIM Op- 
erators". 

climraccept type-key parameters options type stream view &key .-default -.default-type 
&allow-other-keys 

The presentation method responsible for "parsing" the representation of 
type for a particular view. 

climrpresent type-key parameters options object type stream view &key acceptably 
:for-context-type 

The presentation method responsible for displaying the representation of 
object having type type for a particular view view . 

clim:describe-presentation-type type-key parameters options type stream plural- 
count 

The presentation method that is responsible for textually describing the 
type type. 

clim:default-describe-presentation-type description stream plural-count 

Given a string description that describes a presentation type (such as 
"integer") and plural-count (either nil or an integer), this function plu- 
ralizes the string if necessary, prepends an indefinite article if appropri- 
ate, and outputs the result onto stream. 

clim:presentation-typep type-key parameters object type 

The presentation method called when the clim:presentation-typep func- 
tion requires type-specific knowledge. 

climrpresentation-subtypep type-key type putative-supertype 

The presentation method called when the climrpresentation-subtypep 
function requires type-specific knowledge. 

clim:presentation-type-specifier-p type-key parameters options type 

The presentation method that is responsible for checking the validity of 
the parameters and options. 

climraccept-present-default type-key parameters options type stream view default 
default-supplied-p present-p query-identifier &key (.-prompt t) (:active-p t) 
&allow-other-keys 

The presentation method called when climraccept turns into 
climrpresent inside of climraccepting-values. 

climrhighlight-presentation type-key parameters options type record stream state 

The presentation method responsible for drawing a highlighting box for 
the presentation record on the stream stream. 



Utilities for climraccept Presentation Methods 

The utilities documented in this section are typically useful with climraccept (and 
sometimes climrpresent) presentation methods. 
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The following two functions are used to read or write a token (that is, a string): 

clim:read-token stream &key .-timeout :input-wait-handler :pointer-button-press- 
handler xlick-only 

Reads characters from stream until it encounters an activation gesture, a 
delimiter gesture, or a pointer gesture. Returns the accumulated string 
that was delimited by an activation or delimiter gesture, leaving the de- 
limiter unread. 

clim:write-token token stream &key acceptably 

Given the string token, clim:write-token writes it to the stream stream. 

Sometimes, an climraccept method may wish to signal an error while it is parsing 
the user's input, or a nested call to climraccept may signal such an error itself. 
The following functions and conditions may be used: 

climrsimple-parse-error format-string &rest format-arguments 

Signals an error of type climrsimple-parse-error while parsing an input 
token. This function does not return. 

climrinput-not-of-required-type object type 

Reports that input does not satisfy the specified type. 

climrsimple-parse-error 

This condition is signalled when CLIM does not know how to parse some 
sort of user input while inside of climraccept. 

climrinput-not-of-required-type 

This condition is signalled when CLIM gets input that does not satisfy 
the specified type while inside of climraccept. 

Some climraccept methods will want to allow for the completion of partial input 
strings by the user. The following functions are useful for doing that: 

climrcomplete-input stream function &key .-partial-completers :allow-any-input .-pos- 
sibility-printer (:help-displays-possibilities t) 
Reads input from stream, completing from a set of possibilities. 

climrcomplete-from-generator string generator delimiters &key (.-action rcompletej 
.-predicate 

Given an input string string and a list of delimiter characters delimiters 
that act as partial completion characters, climrcomplete-from-generator 
completes against the possibilities that are generated by the function 
generator. 

climrcomplete-from-possibilities string completions delimiters &key (.-action 
rcomplete) .-predicate (:name-key #'first) (:value-key #'secondJ 
Given an input string string and a list of delimiter characters delimiters 
that act as partial completion characters, climrcomplete-from- 
possibilities completes against the possibilities in the sequence comple- 
tions. 
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clim:completing-from-suggestions (stream &rest options &key .-partial-completers 
:allow-any-input .-possibility-printer (:help-displays-possibilities t)) &body 
body 

Reads input from stream, completing from a set of possibilities generated 
by calls to climrsuggest in body. Returns three values: object, success, 
and string. 

climrsuggest name &rest objects 

Specifies one possibility for clim:completing-from-suggestions. comple- 
tion is a string, the printed representation, object is the internal repre- 
sentation. This function has lexical scope and is defined only inside the 
body of clim:completing-from-suggestions. 

climr*completion-gestures* 

A list of gesture names that cause clim:complete-input to complete the 
input as fully as possible. 

clim:*possibilities-gestures* 

A list of gesture names that cause clim:complete-input to display a help 
message and the list of possibilities. 

clim:*help-gestures* 

A list of gesture names that cause climraccept and clim:complete-input 
to display a help message, and, for some presentation types, the list of 
possibilities. 

Sometimes after an climraccept method has read some input from the user, it may 
be necessary to insert a modified version of that input back into the input buffer. 
The following two functions can be used to modify the input buffer: 

climrreplace-input stream new-input &key .start send irescan -.buffer-start 
Replaces stream's input buffer with the string new-input. 

climrpresentation-replace-input stream object type view &key irescan -.buffer-start 

Like climrreplace-input, except that the new input to insert into the in- 
put buffer is gotten by presenting the object object with the presentation 
type type and view view . 

For example, the following climraccept method reads a token followed by a "sys- 
tem" or a pathname, but if the user clicks on either a "system" or a pathname, it 
inserts that object into the input buffer and returns: 
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(cl im:def ine-presen tat ion-method cl im: accept 

((type library) stream (view cl im: textual-view) 
&key default) 
(cl im:with-input-context ('(or system pathname)) (object type) 

(let ((system (dim: accept ' (cl im: token-or-type (: private) system) 

: stream stream :view view 
:prompt nil : display-default nil 
:default default 

additional -del i miter-gestures ' (#\space))) 
file) 
(let ((char (cl im: read-gesture : stream stream))) 
(unless (eql char #\space) 

(cl im: unread-gesture char : stream stream)) 
(when (eql system ':private) 

(setq file (clim:accept 'pathname 

: stream stream :view view 
: prompt "library pathname" 
: display-default t))) 
(if (eql system ':private) file system))) 
(t (cl im:presentation-replace-input stream object type view) 
(values object type)))) 

Occasionally, climraccept methods will want to change the conditions under which 
input fields (or the entire input line) should be terminated. The following macros 
are useful for this: 

climrwith-activation-gestures (additional-gestures &key .-override) &body body 

Specifies gestures that terminate input during the evaluation of body, 
additional-gestures is a gesture spec or a form that evaluates to a list of 
gesture specs. 

climrwith-delimiter-gestures (additional-gestures &key .-override) &body body 

Specifies gestures that terminate an individual token but not the entire 
input sentence during the evaluation of body, additional-gestures is a ges- 
ture spec or a form that evaluates to a list of gesture specs. 

climr*standard-activation-gestures* 

A list of gesture names that cause the current input to be activated. 

climraccept tries to generate meaningful help messages based on the name of the 
presentation type, but sometimes this is not adequate. You can use climrwith- 
accept-help to create more complex help messages. 

clim:with-accept-help options &body body 

Binds the local environment to control HELP and c-? documentation for 
input to climraccept. 

Here are some examples of the use of clim:with-accept-help: 
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(cl im:with-accept-help ((:subhelp "This is a test.")) 
(cl im:accept 'pathname)) 

==> You are being asked to enter a pathname. [ACCEPT did this for you] 
This is a test. [You did this via :SUBHELP] 

(cl im:with-accept-help ((: top-level -help "This is a test.")) 
(clim:accept 'pathname)) 

==> This is a test. [You did this via : TOP-LEVEL-HELP 

(cl im:with-accept-help (((:subhelp :override) "This is a test.")) 
(clim:accept 'pathname)) 

==> You are being asked to enter a pathname. [ACCEPT did this] 

This is a test. [You did this via :SUBHELP] 

(cl im:def ine-presentati on-type test ()) 

(cl im:def ine-presentation-method clim:accept ((type test) stream view &key) 
(values (cl im:with-accept-help 

((:subhelp "A test is made up of three things:")) 
(cl im:completing-f rom-suggestions (...) ...)))) 

(clim:accept 'test) ==> You are being asked to enter a test. 

A test is made up of three things: 

climraccept uses the input editor to read textual input from the user. If you want 
an climraccept method to do any sort of typeout, you must coordinate it with the 
input editor via the climrwith-input-editor-typeout macro. The input editor is dis- 
cussed in more detail in "The Structure of the CLIM Input Editor". 

climrwith-input-editing f&optional stream &key :input-sensitizer .-initial-contents 
.■class) &body body 

Establishes a context in which the user can edit the input he or she 
types in on the stream stream, body is then evaluated in this context, 
and the values returned by body are returned as the values of climrwith- 
input-editing. 

climrwith-input-editor-typeout f&optional stream &key .-erase) &body body 

If, when you are inside of a call to climrwith-input-editing, you want to 
perform some sort of typeout, it should be done inside climrwith-input- 
editor-typeout. 

climrinput-editor-format input-editing-stream format-string &rest format-args 

This function is like format, except that it is intended to be called on 
input editing streams. It arranges to insert "noise strings" in the input 
editor's input buffer. 
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Input Editing and Built-in Keystroke Commands in CLIM 

This is a list of the keystrokes that are built into CLIM's input editor, the specific 
keys assigned in Genera and in Cloe, and how to change them. For more detail on 
the input editor, see the section "The Structure of the CLIM Input Editor". 

Activation Gestures 

Activation gestures terminate an input "sentence", such as a command or any- 
thing else being read by climraccept. When you enter an activation gesture, CLIM 
ceases reading input and executes the input that has been entered. 

The default activation gesture is ttsNewline (also known as ttsReturn). On Genera, 
ttsEnd is also an activation gesture. 

climrwith-activation-gestures Macro 

: activation-gestures to climraccept Option 

radditional-activation-gestures to climraccept Option 

climr*standard-activation-gestures* Variable 

climractivation-gesture-p Function 



Delimiter Gestures 

Delimiter gestures terminate an input "word", such as a recursive call to 
climraccept. There are no global default delimiter gestures; each presentation type 
that recursively calls climraccept specifies its own delimiter gestures and some- 
times offers a way to change them (see Command Processor Gestures, below). 

Delimiter gestures most commonly occur in command lines. When you type a de- 
limiter gesture, CLIM's command processor moves on to read the next field in the 
command line. 

climrwith-delimiter-gestures Macro 

r delimiter-gestures to climraccept Option 

radditional-delimiter-gestures to climraccept Option 

rseparator to climrsubset-completion Presentation Type Option 

rseparator to climrsubset Presentation Type Option 

rseparator to climrsubset-sequence Presentation Type Option 

rseparator to climrsubset-alist Presentation Type Option 

climr*delimiter-gestures* Variable 

climrdelimiter-gesture-p Function 

Abort Gestures 

When an application reads an abort gesture while looking for input, CLIM signals 
the conditionsrabort restart. Aborting is caught by climrdefault-frame-top-level, 
which will abort what the application frame is doing and read another command. 

The default abort gesture is ttsRbort in Genera. In Cloe the default abort gesture 
is ttsEscape or ttsEsc. (Note that this cannot be changed on Cloe). 
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Suspend Gestures 

In Cloe, c-C is similar to c-Suspend in Genera. Its difference is that it causes a 
break in Lisp execution and you can then abort to top level, examine the stack, or 
continue execution. 

Completion Gestures 

Several presentation types, such as member and pathname, support completion of 
partial inputs. When accepting input of one of these types, completion gestures 
and possibilities gestures can be entered. A completion gesture completes the input 
that has been entered so far; if there is more than one possible completion, CLIM 
completes it as much as possible. A possibilities gesture causes CLIM to display 
the possible completions of the input that has been entered so far. 

The default completion gesture is ttMab. On Genera, ttsConplete is also a comple- 
tion gesture. 

The default possibilities gesture is ttscontrol-? in Genera, and the Fl function 
key for Cloe. You can also click the right-hand button on the pointer to get a 
menu of possibilities. 

On Genera, ttMHelp is also a possibilities gesture. 

clim:*completion-gestures* Variable 

clim:*possibilities-gestures* Variable 

clim:*help-gestures* Variable 

Command Processor Gestures 

A command dispatcher character introduces a command (rather than a form) in 
the clim:command-or-form presentation type. The default command dispatcher is 

Colon (:). 

The default character for both terminating and completing command names is 
ttsSpace. This is a delimiter gesture while reading a command name. 

The default character for terminating command arguments is ttsSpace. This is a 
delimiter gesture while reading an argument to a command. 

Pressing a command previewer gesture while entering a command allows a com- 
mand to be entered via a dialog instead of the usual command line. This is an ac- 
tivation gesture while reading a command. On Genera, the default command pre- 
viewer gestures is tt\n-Conplete. On Cloe there is none. 

clim:*command-dispatchers* Variable 

Input Editor Commands 

Keyboard input to climraccept can be edited until an activation gesture is typed to 
terminate it. After an activation gesture is entered, if CLIM cannot parse the in- 
put, the user must edit and re-activate it. The input editor has a number of 
Emacs-like keystroke commands, described in the table below. Prefix numeric argu- 
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ments to input editor commands can be entered using digits and minus sign (-) 
with control, meta, super, or hyper (as in Genera and Emacs). 

The function clim:add-input-editor-command can be used to bind one or more 
keys to an input editor command. Any character can be an input editor command, 
but by convention only non-graphic characters should be used. 



Command 

Forward character 

Forward word 

Forward sexp 
Backward character 

Backward word 

Backward sexp 
Beginning of line 

End of line 

Next line 

Previous line 

Beginning of buffer 

End of buffer 

Delete character 
Delete word 
Delete sexp 
Rubout character 
Rubout word 
Rubout sexp 
Kill line 
Clear all input 
Insert new line 
Insert parens 
Transpose characters 
Transpose words 
Transpose sexps 
Upcase word 
Downcase word 



Genera Key 

control -F 

neta-F 

c-m-F 
control -B 

neta-B 

c-n-B 
control -R 

control -E 

control -N 

control -P 

neta-< 

neta-> 

control -D 

neta-D 

c-n-D 

Rubout 

neta-Rubout 

c-n-Rubout 

control -K 

Clear Input 

control -0 

control -( 

control -T 

meta-T 

c-m-T 

meta-U 

meta-L 



Cloe Key 

control -F 

Right Rrrou 

neta-F 

control -Ri ght Rrrou 

c-n-F 

control -B 

Left Rrrou 

neta-B 

control-Left Rrrou 

c-n-B 

control -R 

Hone 

control -E 

End 

control -N 

Doun Rrrou 

control -P 

Up Rrrou 

neta-< 

control-HOME 

neta-> 

control-END 

control -D 

neta-D 

c-n-D 

Rubout 

neta-Rubout 

c-n-Rubout 

none 

Delete 

none 

none 

control -T 

meta-T 

c-m-T 

meta-U 

meta-L 
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Capitalize word 
Show arglist 
Show variable value 
Show doc string 
Yank from kill ring 
Yank from history 
Yank next thing 
Scroll forward 

Scroll backward 



Dialog Commands 



meta-C 


meta-C 




c-sh-R 


c-sh-R 




c-sh-U 


c-sh-U 




c-sh-D 


c-sh-D 




control -Y 


control ■ 


-Y 


c-m-Y 


c-m-Y 




neta-Y 


neta-Y 




control -\) 


control ■ 


-u 


Scrol 1 






neta-U 


neta-U 




neta-Scrol 1 







An climraccepting-values dialog supports accelerators for exiting and aborting out 
of dialogs. The key bindings can be changed using clim:add-keystroke-to- 
command-table and clim:remove-keystroke-from-command-table in the usual 
way. 

Command Genera Key Cloe Key 

Abort the dialog Rbort Escape 

Exit from the dialog End 

(assuming you are not editing a field) RETURN 



Menu Commands 

At present there are no special keystroke commands for menus. 



Using Views with CLIM Presentation Types 

The climrpresent and climraccept presentation methods can specialize on the view 
in order to define more than one view of the data. For example, a spreadsheet pro- 
gram might define a presentation type for revenue, which can be displayed either 
as a number or a bar of a certain length in a bar graph. Typically, at least one 
canonical view should be defined for a presentation type. For example, the 
climrpresent method for the clim:textual-view view should be defined if the pro- 
grammer wants to allow objects of that type to be displayed textually. 

A more concrete example is the dialog view of the member presentation type, 
which presents the choices in a sort of "radio pushbutton" style. 

CLIM currently supports "default", menu, and dialog views, in both textual and 
gadget styles. Some views act as "indirect" views that are decoded into a more 
specific view; this typically arises for the gadget views. 



Page 1327 



Operators for Views of CLIM Presentation Types 

The following two functions control what view should be used by default on a 
stream, or for any dialog being managed by a particular frame manager. 

clim:stream-default-view stream 

Returns the default view for the stream stream. You can change the de- 
fault view for a stream by using setf on clim:stream-default-view. Calls 
to climraccept default the :view argument from climrstream-default- 
view. 

clim:frame-manager-dialog-view frame-manager 

Returns the view object that should be used to control the look-and-feel 
of climraccepting-values dialogs. 

The following classes and constants are all of the predefined "indirect" views 
(that is, views that might be translated into another view depending on the pre- 
sentation type). Normally, the textual views are not indirected to any other views, 
and CLIM will just use some sort of textual representation for all of the presenta- 
tion types that use a textual view. The gadget dialog view is usually indirected to 
another view, for instance, the member type indirects to clim:+radio-box-view+. 

clim:textual-view 

The class that represents textual views. Textual views are used in most 
command-line oriented applications. 

clim:textual-menu-view 

The class that represents the view that is used inside textual menus. 

clim:textual-dialog-view 

The class that represents the view that is used inside textual 
climraccepting-values dialogs. 

clim:+textual-view+ 

An instance of the class clim:textual-view. 

clim:+textual-menu-view+ 

An instance of the class clim:textual-menu-view. Inside climrmenu- 
choose, the default view for the menu stream may be bound to 
clim:+textual-menu-view+. 

clim:+textual-dialog-view+ 

An instance of the class clim:textual-dialog-view. Inside climraccepting- 
values, the default view for the dialog stream may be bound to 
clim:+textual-dialog-view+. 

clim:gadget-view 

The class that represents gadget views. Gadgets views are used for 
toolkit-oriented applications. 

clim:gadget-menu-view 

The class that represents the view that is used inside toolkit-style 
menus. 
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clim:gadget-dialog-view 

The class that represents the view that is used inside toolkit-style 
climraccepting-values dialogs. 

clim:+gadget-view+ 

An instance of the class clim:gadget-view. 

clim:+gadget-menu-view+ 

An instance of the class clim:gadget-menu-view. Inside climrmenu- 
choose, the default view for the menu stream may be bound to 
clim:+gadget-menu-view+. 

clim:+gadget-dialog-view+ 

An instance of the class clim:gadget-dialog-view. Inside climraccepting- 
values, the default view for the dialog stream may be bound to 
clim:+gadget-dialog-view+. 

The following is a table of presentation types and the actual view they map to: 

Type Gadget 

climrcompletion clim:+radio-box-view+ 

climrsubset-completion clim:+check-box-view+ 

climrboolean clim:+toggle-button-view+ 

real clim:+slider-view+ 

float clim:+slider-view+ 

integer clim:+slider-view+ 

All others clim:+text-field-view+ 



Functions that Operate on CLIM Presentation Types 

These are some general-purpose functions that operate on CLIM presentation 
types. 

clim:describe-presentation-type presentation-type &optional (stream *standard- 
output*) (plural-count I) 
Describes the presentation-type on the stream. 

clim:presentation-typep object type 

Returns t if object is of the type specified by type, otherwise returns nil. 

clim:presentation-type-of object 

Returns the presentation type of the object object. 

climrpresentation-subtypep type putative-supertype 

Answers the question "Is the type specified by type a subtype of the type 
specified by putative-supertypeT' . 

clim:with-presentation-type-decoded (name-var &optional parameters-var options- 
var) type &body body 

The specified variables are bound to the components of the presentation 
type specifier, the forms in body are evaluated, and the values of the last 
form are returned. 
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clim:with-presentation-type-options (type-name type) &body body 

Variables with the same name as each option in the definition of the 
presentation type are bound to the option values in type, if present, or 
else to the defaults specified in the definition of the presentation type. 
The forms in body are evaluated in the scope of these variables and the 
values of the last form are returned. 

clim:with-presentation-type-parameters (type-name type) &body body 

Variables with the same name as each parameter in the definition of the 
presentation type are bound to the parameter values in type, if present, 
or else to the defaults specified in the definition of the presentation type. 



Presentation Translators in CLIM 



Concept of Presentation Translators in CLIM 

CLIM provides a mechanism for translating between types. In other words, within 
an input context for presentation type A, the translator mechanism allows a pro- 
grammer to define a translation from presentations of some other type B to objects 
that are of type A. 

You can define presentation translators to make the user interface of your applica- 
tion more flexible. For example, suppose the input context is expecting a command. 
In this input context, all displayed commands are sensitive, so the user can point 
to one to execute it. However, suppose the user points to another kind of presented 
object, such as a student. In the absence of a presentation translator, the student 
is not sensitive because the user must enter a command and cannot enter anything 
else to this input context. 

In the presence of a presentation translator that translates from students to com- 
mands, however, the presented student would be sensitive. In one scenario, the 
presented student is highlighted, and the middle pointer button does "Show Tran- 
script" of that student. 

A presentation translator defines how to translate from one presentation type to 
another. In the scenario above, the input context is climrcommand. A user-defined 
presentation translator states how to translate from the student presentation type 
to the climrcommand presentation type. 

The concept of translating from an arbitrary presentation type to a command is so 
useful that CLIM provides a special macro for this purpose, climrdefine- 
presentation-to-command-translator. You can think of these presentation-to- 
command translators as a convenience for the users; users can select the command 
and give the argument at the same time. 

Presentation-to-command translators make it easier to write applications that give 
a "direct manipulation" feel to the user. 



What Controls Sensitivity in CLIM? 
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A presentation that appears on the screen can be sensitive. This means that the 
presentation can be operated on directly by using the pointer. In other words, the 
presentation is relevant to the current context. When the user moves the pointer 
over a sensitive presentation, the presentation is highlighted to indicate that it is 
sensitive. (In rare cases, the highlighting of some sensitive presentations is turned 
off.) 

Sensitivity is controlled by three factors: the current input context, the location of 
the pointer, and the chord of modifier keys being pressed. 

• Input context type — a presentation type describing the type of input currently 
being accepted. 

• Pointer location — the pointer is pointing at a presentation or a blank area on 
the screen. 

• Modifier keys — these are control, meta, super, hyper, and shift. These keys ex- 
pand the space of available gestures beyond what is available from the pointer 
buttons. Note that some platforms might not provide any way to input all of the 
modifier keys, but most provide at least control, meta, and shift. 

Presentation translators are the link among these three factors. 

A presentation translator specifies the conditions under which it is applicable, a 
description to be displayed, and what to do when it is invoked by clicking the 
pointer. 

A presentation is sensitive if there is at least one applicable translator that could 
be invoked by clicking a button with the pointer at its current location and the 
modifier keys in their current state. If there is no applicable translator, there is 
no sensitivity, and no highlighting. 

Each presentation translator has two associated presentation types, its from- 
presentation-type and to-presentation-type, which are the primary factors in its ap- 
plicability. The basic idea is that a presentation translator translates an output 
presentation into an input presentation. Thus a presentation translator is applica- 
ble if the type of the presentation at the pointer "matches" from-presentation-type 
and the input context type "matches" to-presentation-type. (We define what 
"match" means below.) Each presentation translator is attached to a particular 
pointer gesture, which is a combination of a pointer button and a set of modifier 
keys. Clicking the pointer button while holding down the modifier keys invokes the 
translator. 

A translator produces an input presentation consisting of an object and a presenta- 
tion type, to satisfy the program accepting input. The result of a translator might 
be returned from climraccept, or might be absorbed by a parser and provide only 
part of the input. An input presentation is not actually represented as an object. 
Instead, a translator's body returns two values. The object is the first value. The 
presentation type is the second value; it defaults to to-presentation-type if the body 
returns only one value. 
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Applicability of CLIM Presentation Translators 

When CLIM is waiting for input (that is, inside a clim:with-input-context), it is 
responsible for determining what translators are applicable to which presentations 
in a given input context. This loop both provides feedback in the form of highlight- 
ing sensitive presentations, and is responsible for calling the applicable translator 
when the user presses a pointer button. 

clim:with-input-context uses clim:frame-find-innermost-applicable-presentation 

(via climrhighlight-applicable-presentation) as its "input wait" handler, and 
clim:frame-input-context-button-press-handler as its button press "event han- 
dler". 

Given a presentation, an input context established by clim:with-input-context, and 
a user gesture, translator matching proceeds as follows. 

The set of candidate translators is initially those translators accessible in the com- 
mand table in use by the current application. For more information, see the sec- 
tion "Command Objects in CLIM". 

A translator "matches" if all of the following are true. These tests are performed 
in the order listed. 

1. The presentation's type is climrpresentation-subtypep of the translator's 
from-presentation-type, ignoring type parameters (for example, if from- 
presentation-type is number and the presentation's type is integer or 
float, or if from-presentation-type is (or integer string) and presenta- 
tion's type is integer). 

2. The translator's to-presentation-type is climrpresentation-subtypep of the 
input context type, ignoring type parameters. 

3. The translator's gesture either is t, or is the same as the gesture that 
the user could perform with the current chord of modifier keys. 

4. If the from-presentation-type has parameters, the presentation's object is 
climrpresentation-typep of the translator's from-presentation-type. 

5. The translator's tester returns a non-nil value. If there is no tester, the 
translator behaves as though the tester always returns t. 

6. If there are parameters in the input context type and the rtester- 
definitive option is not used in the translator, the value returned by the 
body of the translator must be climrpresentation-typep of the input con- 
text type. In climrdefine-presentation-to-command-translator and 
climrdefine-presentation-action the tester is always taken to be defini- 
tive. 

The algorithm is somewhat more complicated in the face of nested presentations 
and nested input contexts. In this case, the applicable presentation is the smallest 
presentation that matches the innermost input context (that is, translators match- 
ing inner contexts precede translators matching outer contexts, and, in the same 
input context, inner presentations precede outer presentations). 
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Sometimes there may be nested presentations that have exactly the same bounding 
rectangle. In this case, it is not possible for a user to unambiguously point to just 
one of the nested presentations. Therefore, when CLIM has located the innermost 
applicable presentation in the innermost input context, it then searches for outer 
presentations that have exactly the same bounding rectangle, and checks to see if 
there are any applicable translators for those presentations. If there are multiple 
applicable translators, CLIM chooses the one having the highest priority. 

There can be more than one translator that matches a presentation for the same 
gesture in a given input context. When this happens, the first translator is chosen, 
based on the following ordering: 

1. Translators with a higher "high order" priority precede translators with 
a lower "high order" priority. This allows you to create an "overriding" 
translator that always precedes any other applicable translators. 

2. Translators with a more specific from-presentation-type precede transla- 
tors with a less specific from-presentation-type. 

3. Translators with a higher "low order" priority precede translators with 
a lower "low order" priority. This allows you to "break ties" between 
translators that translate from the same type. 

4. Translators from the current command table precede translators inherit- 
ed from superior command tables. 

See the description of the rpriority option in climrdefine-presentation-translator. 

Input Contexts in CLIM 

Roughly speaking, the current input context indicates what type of input CLIM is 
currently asking the user for. These are the ways you can establish an input con- 
text in CLIM: 

climraccept 

clim:accept-from-string 

The command loop of an application 

Nested Input Contexts in CLIM 

The input context designates a presentation type. However, the way to accept one 
type of object may involve accepting other types of objects as part of the proce- 
dure. (Consider the request to accept a complex number. It is likely to involve ac- 
cepting two real numbers.) Such input contexts are called nested. In the case of a 
nested input context, several different context presentation types can be available 
to match the to-presentation-types of presentation translators. 

Each level of input context is established by a call to climraccept. The macro 
climrwith-input-context also establishes a level of input context. 

The most common cause of input context nesting is accepting compound objects. 
For example, you might define a command called Show File, which reads a se- 
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quence of pathnames. When reading the argument to the Show File command, the 
input context contains pathname nested inside of (sequence pathname). Accept- 
able keyboard input is a sequence of pathnames separated by commas. A presenta- 
tion translator that translates to a (sequence pathname) supplies the entire argu- 
ment to the command, and the command processor moves on to the next argument. 
A presentation translator that translates to a pathname is also applicable. It sup- 
plies a single element of the sequence being built up, and the command processor 
awaits additional input for this argument, or entry of a SPRCE or RETURN to termi- 
nate the argument. 

When the input context is nested, sensitivity computations consider only the inner- 
most context type that has any applicable presentation translators for the currently 
pressed chord of modifier keys. 



Nested Presentations in CLIM 

Presentations can overlap on the screen, so there can be more than one presenta- 
tion at the pointer location. Often when two presentations overlap, one is nested 
inside the other. 

One cause of nesting is presentations of compound objects. For example, a se- 
quence of pathnames has one presentation for the sequence, and another for each 
pathname. 

When there is more than one candidate presentation at the pointer location, CLIM 
must decide which presentation is the sensitive one. It starts with the innermost 
presentation at the pointer location and works outwards through levels of nesting 
until a sensitive presentation is discovered. This is the innermost presentation that 
has any applicable presentation translators, to any of the nested input context 
types, for the currently pressed chord of modifier keys. Searching in this way en- 
sures that a more specific presentation is sensitive. Note that nested input con- 
texts are searched first, before nested presentations. For presentations that over- 
lap, the most recently presented is searched first. 



Gestures and Gesture Names in CLIM 

A gesture in CLIM is an input action by the user, such as typing a character or 
clicking a pointer button. A pointer gesture refers to those gestures that involve us- 
ing the pointer. 

A gesture spec is a portable way of naming a gesture. For example, the non- 
portable "character" #\control-shift-C has a gesture spec of (:C : control 
: shift). For convenience, the gesture spec for standard Common Lisp characters 
(the printing characters, including alphanumerics, ASCII symbols, and #\Space), 
you can use the character itself as the gesture spec. 

An event is a CLIM object that represents a gesture by the user. (The most impor- 
tant pointer events are those of class clim:pointer-button-event.) 

A gesture name is a symbol that names a gesture or gesture spec. CLIM defines 
the following gesture names: 
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rselect For the most commonly used translator on an object. For example, 

use the rselect gesture while reading an argument to a command to 
use the indicated object as the argument. 

rdescribe For translators that produce a description of an object (such as 

showing the current state of an object). For example, use the rde- 
scribe gesture on an object in a CAD program to display the param- 
eters of that object. 

rdelete For translators that delete an object. 

redit For translators that edit an object. 

rmodify For translators that somehow modify an object. 

rmenu For translators that pop up a menu. 

These correspond to the following events in Genera and in Cloe: 





Genera 


Cloe 


Gesture Name 


Gesture 


Gesture 


rselect 


click Left 


click Left 


rdescribe 


click Middle 


click Middle 
click A-Right 


rmenu 


click Right 


click Right 


rdelete 


click sh-Middle 




redit 


click m-Left 




rmodify 


click c-m-Right 





The special gesture name nil is used in translators that are not directly invokable 
by a pointer gesture. Such a translator can be invoked only from a menu. 

The special gesture name t means that the translator is available on every ges- 
ture. 

You can use climrdefine-gesture-name to define your own gesture names. Avoid 
the temptation to define pointer gestures named rleft, rmiddle, and rright; doing 
so can lead you to write less portable applications. If your program use only ges- 
ture names, they are more portable than if you to specific pointer buttons and key- 
board keys. 



Operators for Gestures in CLIM 

The following operators can be used to add or remove new gesture names: 

climradd-gesture-name name type gesture-spec &key (.-unique t) 

Adds a gesture named name (a symbol) to the set of all gesture names. 
If .-unique is t, an error is signalled if there is already a gesture named 
name. 
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clim:delete-gesture-name gesture-name 

Removes the gesture named gesture-name. 

clim:define-gesture-name name type gesture-spec &key (.-unique t) 

Defines a gesture named name by calling clim:add-gesture-name. 

The following operators can be used to examine CLIM event objects or match 
CLIM event objects against gesture names. 

clim:event-sheet event 

Returns the window on which event occurred. 

clim:event-modifier-state event 

Returns the state of the keyboard's shift keys when the event event oc- 
curred. 

clim:pointer-event-button pointer-button-event 

Returns the button number that was pressed when the pointer button 
event pointer-button-event occurred. The values this can take are 
clim:+pointer-left-button+, clim:+pointer-middle-button+, or 

clim:+pointer-right-button+. 

clim:pointer-event-x pointer-event 

Returns the X position of the pointer when the pointer-event occurred. 

clim:pointer-event-y pointer-event 

Returns the Y position of the pointer when the pointer-event occurred. 

clim:keyboard-event-key-name keyboard-event 

Returns the name of the key that was pressed or released in order to 
generate the keyboard event. 

clim:keyboard-event-character keyboard-event 

Returns the character corresponding to the key that was pressed or re- 
leased, if there is a corresponding character. 

clim:event-matches-gesture-name-p event gesture-name &optional port 

Returns t if the device event event "matches" the gesture named by ges- 
ture-name. 

clim:modifier-state-matches-gesture-name-p state gesture-name 

Returns t if the modifier state state "matches" the modifier state of the 
gesture named by gesture-name. 

clim:make-modifier-state &rest modifiers 

Given a set of modifier key names, clim:make-modifier-state returns a 
modifier state corresponding to those keys. 

The following constants are the values that can be taken on by climrevent- 
modifier-state. Note that these are bit values that can be combined with "logical 
or" when multiple modifier keys are being held down by the user. 

clim:+shift-key+ 

The modifier state bit that corresponds to the user holding down the 
shift key on the keyboard. 
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clim:+control-key+ 

The modifier state bit that corresponds to the user holding down the 
control key on the keyboard. 

clim:+meta-key+ 

The modifier state bit that corresponds to the user holding down the me- 
ta key on the keyboard. 

clim:+super-key+ 

The modifier state bit that corresponds to the user holding down the su- 
per key on the keyboard. 

clim:+hyper-key+ 

The modifier state bit that corresponds to the user holding down the hy- 
per key on the keyboard. 

The following constants are the values that can be taken on by climrpointer- 
event-button. 

clim:+pointer-left-button+ 

The value returned by clim:pointer-event-button that corresponds to the 
user having pressed or released the lefthand button on the pointer. 

clim:+pointer-middle-button+ 

The value returned by clim:pointer-event-button that corresponds to the 
user having pressed or released the middle button on the pointer. 

clim:+pointer-right-button+ 

The value returned by clim:pointer-event-button that corresponds to the 
user having pressed or released the righthand button on the pointer. 



CLIM Operators for Defining Presentation Translators 

You can write presentation translators that apply to blank areas of the window, 
that is, areas where there are no presentations. Use clim:blank-area as the from- 
presentation-type. There is no highlighting when such a translator is applicable 
since there is no presentation to highlight. You can write presentation translators 
that apply in any context by supplying nil as the to-presentation-type. 

climrdefine-presentation-translator supports the general case, and climrdefine- 
presentation-to-command-translator supports a common idiom. 

climrdefine-presentation-translator name (from-type to-type command-table &key 
(.-gesture 'rselectj .-tester .-tester-definitive .-documentation .-pointer- 
documentation (:menu t) .-priority) arglist &body body 

Defines a presentation translator named name which translates from ob- 
jects of type from-type to objects of type to-type. 

clim:define-presentation-to-command-translator name (from-type command-name 
command-table &key (-gesture 'rselectj .-tester .-documentation .-pointer- 
documentation (-menu t) .-priority (-.echo t)) arglist &body body 
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Defines a presentation translator that translates a displayed presentation 
into a command. 

climrdefine-presentation-action name (from-type to-type command-table &key (.'ges- 
ture 'rselect) .-tester .-documentation .-pointer-documentation (:menu t) .-pri- 
ority) arglist &body body 

This is similar to climrdefine-presentation-translator, except that the 
body of the action is not intended to return a value, but should instead 
side-effect some sort of application state. Note that actions do not satisfy 
requests for input (as translators do). 

clim:define-drag-and-drop-translator name (from-type to-type destination-type com- 
mand-table &key (-gesture 'rselect) .-tester .-documentation (-menu t) .-priori- 
ty .-feedback .-highlighting .-pointer-cursor) arglist &body body 
Defines a "drag and drop" (or "direct manipulation") translator named 
name that translates from objects of type from-type to objects of type to- 
type when a "from presentation" is "picked up", "dragged" over, and 
"dropped" on a "to presentation" having type destination-type. 

clim:blank-area 

The presentation type that represents all the places in a window where 
there is no applicable presentation. CLIM provides a single "null pre- 
sentation" (represented by the value of clim:*null-presentation*) of this 
type. 

clim:*null-presentation* 

The "null" presentation, which occupies any part of a window where 
there are no presentations matching the current input context. 



Examples of Defining Presentation Translators in CLIM 

Defining a Translation from Pathname to Integer 

Here is an example that defines a presentation translator to extract the version 
number, an integer object, from a pathname presentation. Users have the options 
of typing in a version number to the input prompt or clicking on a pathname pre- 
sentation that includes a version number. 

(cl im:def ine-presen tat ion- translator pathname- vers ion 
(pathname integer my-command-table 
: documentation "File version number" 
: gesture : select 

;; Only works for pathnames with numeric versions 
:tester ((object) (integerp (pathname-version object))) 
: tester-definitive t) 
(object) 
(pathname-version object)) 

(cl im:present #P" KOALA :>KJones>foo. 1 isp. 17" 'pathname) 
(clim:accept 'integer) 
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Defining a Presentation-to-Command Translator 

The following example defines the Delete File presentation-to-command translator: 

(cl i m : def i ne-presentati on-to-command-transl ator del ete-f i 1 e 
(pathname corn-del ete-f ile my-command-table 
: documentation "Delete this file" 
:gesture :delete) 
(object) 
(1 ist object)) 

Defining a Presentation Translator from the Blank Area 

When you are writing an interactive graphics routine, you will probably encounter 
the need to have commands available when the mouse is not over any object. To 
do this, you write a translator from the blank area. 

The presentation type of the blank area is clim:blank-area. You will often want to 
use the x and y arguments to the translator. 

For example: 

(cl im : def i ne-presentati on-to-command-transl ator add-ci rcle-here 
(cl im: blank-area com-add-ci rcle my-command-table 
: documentation "Add a circle here.") 

(x y) 

(list x y)) 

Defining a Presentation Action 

Presentation actions are only rarely needed. Often a presentation-to-command 
translator is more appropriate. One example where actions are appropriate is when 
you wish to pop up a menu during command input. Here is how CLIM's general 
menu action could be implemented: 

(cl im:def i ne-presentati on-act ion presentation-menu 
(t nil cl im: global -command-table 
: tester-definitive t 
documentation "Menu" 
:menu nil 
:gesture :menu) 
(presentation frame window x y) 
(cl im:cal 1 -presentation-menu presentation cl im:*input-contextx 

frame window x y 
:for-menu t)) 



Low Level Functions for CLIM Presentation Translators 

Some applications may wish to deal directly with presentation translators, for ex- 
ample, if you are tracking the pointer yourself and wish to locate sensitive presen- 
tations, or want to generate a list of applicable translators for a menu. The follow- 
ing functions are useful for finding and calling presentation translators directly. 
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climrfind-presentation-translators from-type to-type command-table 

Returns a list of all the translators associated with frame's current com- 
mand table that translate from from-type to to-type, without taking into 
account any type parameters or testers. 

climrfind-applicable-translators presentation input-context frame window x y &key 
.-event .-modifier-state :for-menu :fastp 

Returns a list of translators that apply to presentation in the input con- 
text input-context. 

clim:presentation-matches-context-type presentation context-type frame window x y 
&key -.event (-.modifier-state 0) 

Returns t if there are any translators that translate from presentation's 
type to context-type. 

climrtest-presentation-translator translator presentation context-type frame window 
x y &key .-event (.-modifier-state 0) :for-menu 

Returns t if the translator translator applies to the presentation presenta- 
tion in input context type context-type. 

climrcall-presentation-translator translator presentation context-type frame event 
window x y 

Calls the function that implements the body of translator on 
presentation's object, and passes presentation, context-type, frame, event, 
window, x, and y to the body of the translator as well. 

climrdocument-presentation-translator translator presentation context-type frame 
event window x y &key (stream *standard-output*J .-documentation-type 
Computes the documentation string for translator, sending it to stream. 

clim:call-presentation-menu presentation input-context frame window x y &key 
(:for-menu t) .-label 

Finds all the applicable translators for presentation in the input context 
input-context, creates a menu that contains all of the translators, and 
pops up a menu from which the user can choose a translator. 

The following functions are useful for finding an application presentation in an 
output history. 

climrfind-innermost-applicable-presentation input-context stream x y &key (-frame 
clim:*application-frame*) .-modifier-state .-event 

Given an input context input-context, an output recording window stream 
window, and X and Y positions x and y, this function returns the inner- 
most presentation that matches the innermost input context, using the 
translator matching algorithm. 

climrthrow-highlighted-presentation presentation input-context button-press-event 

Calls the applicable translator for a given presentation, input-context, and 
button-press-event (that is, the one corresponding to the user clicking a 
pointer button while over the presentation), and returns an object and a 
presentation type. 
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clim:frame-find-innermost-applicable-presentation frame input-context stream x y 
Locates and returns the innermost applicable presentation on the window 
stream at the position indicated by x and y, in the input context input- 
context, on behalf of frame. The default method simply calls climrfind- 
innermost-applicable-presentation. 

clim:frame-input-context-button-press-handler frame stream button-press-event 

This function is responsible for handling user pointer gestures on behalf 
of frame, stream is the window on which button-press-event took place. 
The default method calls climrthrow-highlighted-presentation on the 
currently applicable presentation. 

climrhighlight-applicable-presentation frame stream input-context &optional 
(prefer-pointer-window t) 

The "input wait" handler used by clim:with-input-context, responsible 
for highlighting and unhighlighting presentations. 

climrset-highlighted-presentation stream presentation &optional (prefer-pointer- 
window t) 
Highlights the presentation presentation on stream. 

climrunhighlight-highlighted-presentation stream &optional (prefer-pointer-window 

t) 

Unhighlights any highlighted presentations on stream. 

Most applications will never need to use any of these functions. 
Defining Application Frames in CLIM 

Concepts of CLIM Application Frames 

Application frames (or simply, frames) are the central mechanism in CLIM for pre- 
senting an application's user interface. A frame contains the state of the applica- 
tion and a hierarchy of panes. 

The look and feel of an application frame is managed by a frame manager. The 
frame manager is responsible for creating the concrete, window system dependent 
gadget that corresponds to each abstract gadget. It is also responsible for the look 
and feel of menus, dialogs, pointer documentation, and so forth. 

Application frames provide support for a standard interaction processing loop, like 
the Lisp "read-eval-print" loop. You are required to write only the code that imple- 
ments the frame-specific commands and output display functions. A key aspect of 
this interaction processing loop is the separation of the specification of the frame's 
commands from the specification of the end-user interaction style. 

The standard interaction loop consists of reading an input "sentence" (a command 
and all of its operands), processing the input (by executing the command), and up- 
dating the displayed information as appropriate. CLIM implementations are free to 
run the display update part of the loop at a lower priority than command execu- 
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tion. For example, some implementations may choose not to update the display if 
there is typed-ahead input. Also, command execution and display will not occur si- 
multaneously, so user-defined functions need not cope with multiprocessing. 

Note that this definition of the standard interaction loop does not constrain the in- 
teraction style to command-line interfaces. The input sentence may be entered via 
single keystrokes, pointer input, menu selection, or by typing full command lines. 
CLIM allows the application implementor to choose what subset of approaches will 
be applicable for each individual command. Furthermore, an application's interac- 
tion loop isn't constrained to read only commands; it could read lower-level events 
in order to implement a completely different interaction style. 

For more information about how to use CLIM application frames, see the section 
"What is an Application?". 



Defining CLIM Application Frames 

climrdefine-application-frame defines CLIM application frames. Application frames 
are represented by CLOS classes which inherit from climrstandard-application- 
frame. You can specify a name for the application class, the superclasses (if there 
are any beyond clim:standard-application-frame), the slots of the application 
class, and options. 

clim:define-application-frame defines a class with the following characteristics: 

• inherits some behavior and slots from the class climrstandard- 
application-frame, 

• inherits other behavior and slots from any other superclasses which you 
specify explicitly, and 

• has other slots, as explicitly specified by slots. 

The following options are used by the class clim:standard-application-frame: 

rpanes or :pane 

rlayouts 

:top-level 

:command-table 

: disabled-commands 

rcommand-definer 

:menu-bar 

Note that rcommand-definer doesn't actually affect a slot, but instead provides an 
override for the name of the default application command definer macro that auto- 
matically generated by climrdefine-application-frame. 

For detailed information about CLIM application frames, see the macro 
climrdefine-application-frame. 
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Panes in CLIM 

CLIM panes are similar to the gadgets or widgets of other toolkits. They can be 
used by application programmers to compose the top-level user interface of their 
applications, as well as auxiliary components such as menus and dialogs. The ap- 
plication programmer provides an abstract specification of the pane hierarchy, 
which CLIM uses in conjunction with user preferences and other factors to select 
a specific "look and feel" for the application. In many environments a CLIM appli- 
cation can use the facilities of the host window system toolkit via a set of adaptive 
panes, allowing a portable CLIM application to take on the look and feel of an ap- 
plication written using the toolkits supplied by the underlying window system. 

Panes are rectangular objects that are implemented as special sheet classes. An 
application will typically construct a tree of panes that divide up the screen space 
allocated to the application frame. The various CLIM pane types can be character- 
ized by whether they have child panes or not: panes that can have other panes as 
children are called composite panes, and those that don't are called leaf panes. 
Composite panes are used to provide a mechanism for spatially organizing ("laying 
out") other panes. There are two main kinds of leaf panes: gadgets and "applica- 
tion" panes. Leaf panes that implement gadgets have a particular appearance 
(often defined by the underlying window system toolkit) and react to user input by 
invoking some kind of callback. "Application" panes provide an area of the appli- 
cation's screen real estate that can be used by the application to present applica- 
tion specific information. CLIM provides a number of these application pane types 
that allow the application to use CLIM's graphics and extended stream facilities. 

Abstract panes are gadget panes that are defined only in terms of their program- 
mer interface, or behavior. The protocol for an abstract pane (that is, the specified 
set of initialization options, accessors, and callbacks) is designed to specify the 
pane in terms of its overall purpose, rather then in terms of its specific appear- 
ance or particular interactive details. The purpose of this abstract definition is to 
allow multiple implementations of the abstract pane, each defining its own specific 
look and feel. CLIM can then select the appropriate pane implementation based on 
factors outside the control of the application, such as user preferences or the look 
and feel of the host operating environment. A subset of the abstract panes, the 
adaptive panes, have been defined to integrate well across all CLIM operating 
platforms. 

Basic Pane Construction 

Applications typically define the hierarchy of panes used in their frames using the 
:pane or :panes options of clim:define-application-frame. These options generate 
the body of methods on functions that are invoked when the frame is being adopt- 
ed into a particular frame manager, so the frame manager can select the specific 
implementations of the abstract panes. 

There are two basic interfaces to constructing a pane: clim:make-pane of an 
"abstract" pane class name, or closrmake-instance of a "concrete" pane class. 
The former approach is generally preferable, since it results in more portable code. 
However, in some cases the programmer may wish to instantiate panes of a specif- 



Page 1343 



ic class (such as an clim:hbox-pane or a clim:vbox-pane). In this case, using 
closrmake-instance directly circumvents the abstract pane selection mechanism. 
However, the closrmake-instance approach requires the application programmer to 
know the name of the specific pane implementation class that is desired, and so is 
inherently less portable. By convention, all of the concrete pane class names, in- 
cluding those of the implementations of abstract pane protocol specifications, end 
in "-pane". 

Using clim:make-pane instead of closrmake-instance invokes the "look and feel" 
realization process to select and construct a pane. Normally this process is imple- 
mented by the frame manager, but it is possible for other "realizers" to imple- 
ment this process. clim:make-pane is typically invoked using an abstract pane 
class name, which by convention is a symbol in the CLIM package that doesn't in- 
clude the "-pane" suffix. (This naming convention distinguishes the names of the 
abstract pane protocols from the names of classes that implement them.) Program- 
mers, however, are allowed to pass any pane class name to clim:make-pane in 
which case the frame manager will generally instantiate that specific class. 

See the function clim:make-pane. 

See the macro clim:make-clim-stream-pane. 



Using the rpanes Option to clim:define-application-frame 

The rpanes option to climrdefine-application-frame is used to describe the panes 
used by the application frame. It takes a list of pane-descriptions. Each pane- 
description can be one of two possible formats: 

• A list consisting of a pane-name (which is a symbol), a pane-type, and pane- 
options, which are keyword-value pairs, pane-options is evaluated at load time. 

• A list consisting of a pane-name (which is a symbol), followed by an expression 
that is evaluated to create the pane. See the macro climrmake-clim-stream- 
pane and the function clim:make-pane. 

The pane-types are: 

: application 

Application panes are stream panes used for the display of applica- 
tion-generated output. See the class clim:application-pane. See the 
macro clim:make-clim-application-pane. 

rinteractor 

Interactor panes are stream panes that provide a place for the user 
to do interactive input and output. See the class climrinteractor- 
pane. See the macro clim:make-clim-interactor-pane. 

: accept- values 

These panes provide for the display of a "modeless" 
climraccepting-values dialog. See the class 

clim:accept-values-pane. See the section "Using an : accept- values 
Pane in a CLIM Application Frame". 
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rpointer-documentation 

These panes provide for pointer documentation. If such a pane is 
specified, then when the pointer moves over different areas of the 
frame, this pane displays documentation of the effect of clicking the 
pointer buttons. 

If the host window system has its own way of displaying pointer 
documentation, this pane may be omitted automatically from the 
layout. 



See the class clim:pointer-documentation-pane. 

:command-menu 

Command menu panes are used to hold a menu of application com- 
mands. The default display function is clim:display-command-menu 
which, by default, displays the current command table of the frame. 
You can display a different command table by supplying the 
:command-table argument to clim:display-command-menu. 

Many host window systems provide a menu bar, so having panes of 
type :command-menu is not common. 

See the class clim:command-menu-pane. 

rtitle Title panes are used for displaying the title of the application. The 

default title is a "prettied up" version of the name of the applica- 
tion frame's class. 

Many host window systems will automatically display the frame's ti- 
tle in a title bar, so this is only rarely useful. 

See the class clim:title-pane. 
The following pane-options are usable by all pane types, unless otherwise noted. 

rwidth, rheight, :min-width, :min-height, :max-width, and :max-height 

Provide space requirement specs that specify the sized of the pane. 
The values the space requirements can take are described in "Using 
the :LAYOUTS Option to CLIM:DEFINE-APPLICATION-FRAME". 

rbackground and rforeground ink 

Provide initial values for climrmedium-foreground and 
climrmedium-background for the pane. 

:text-style text-style 

Specifies a text style to use in the pane. The default depends on the 
pane type. 

rborders Controls whether borders are drawn around CLIM stream panes (t 
or nil). The default is t. The value may also be a list, in which case 
the value is used as options to climroutlining. 

rspacing Controls whether there is some whitespace between the border and 
the viewport for a CLIM stream pane (t or nil). The default is t. 
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The value may also be a list, in which case the value is used as op- 
tions to climrspacing. 

:scroll-bars scroll-bar-spec 

A scroll-bar-spec can be :both (the default for : application panes), 
rhorizontal, rvertical, :none, or nil. The pane will have only those 
scroll bars which were specified. :none means that the pane will 
support scrolling, but does not have any visible scroll bars, nil 
means that the pane will not support scrolling at all. 

:display-after-commands 

One of t, nil, or :no-clear. If t, the "print" part of the read-eval- 
print loop runs the display function; this is the default for most 
pane types. If nil, you are responsible for managing the display af- 
ter commands. 

:no-clear behaves the same as t, with the following change. If you 
have not specified rincremental-redisplay t, then the pane is nor- 
mally cleared before the display function is called. However, if you 
specify :display-after-commands :no-clear, then the pane is not 
cleared before the display function is called. 

: display-function display-spec 

Where display-spec is either the name of a function or a list whose 
first element is the name of a function. The function is to be ap- 
plied to the application frame, the pane, and the rest of display-spec 
if it was a list when the pane is to be redisplayed. 

The function must accept two required arguments (the frame and 
the pane), plus the two keyword arguments :max- width and :max- 
height. 

One example of a predefined display function is climrdisplay- 
command-menu. 

rdisplay-string string 

(for rtitle panes only) The string to display. The default is the 
frame's pretty name. 

rlabel string 

A string to be used as a label for the pane, or nil (the default). 

:incremental-redisplay boolean 

If t, CLIM runs the display function inside of an climrupdating- 
output form. The default is nil. 

:end-of-line-action, :end-of -page-action 

Initial values of the corresponding attributes. See the macro 
clim:with-end-of-line-action and see the macro clim:with-end-of- 
page-action. 

rinitial-cursor-visibility 

:off means make the text cursor visible if the window is waiting for 
input. :on means make it visible all the time, nil means that the 
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cursor is never visible. The default is :off for rinteractor and 
: accept- values panes, and nil for other panes. 

routput-record 

Specify this if you want a different output history mechanism than 
the default (which is clim:standard-tree-output-history). For ex- 
ample, a graphic editing program might supply a value of: 

(make- instance 'cl im: r- tree-output-history) 

Besides clim:standard-tree-output-history and climrr-tree-output- 
history, you can also use climrstandard-sequence-output-history. 

:draw-p, :record-p boolean 

Specifies the initial state of drawing and output recording. 

:default-view view 

Specifies the view object to use for the stream's default view. 

:text-margin integer 

Text margin to use if clim:stream-text-margin isn't set. This de- 
faults to the width of the viewport. 

rvertical-spacing integer 

Amount of extra space between text lines. 

rpointer-cursor 

Specifies the pointer cursor to use when the pointer is over this 
pane. 

:event-queue 

Specifies the event queue to be used by this pane. The default is to 
share the event queue with the top-level sheet, so that all the panes 
in the frame use the same event queue. 



Using the :LAYOUTS Option to CLIMrDEFINE-APPLICATION-FRAME 

A layout is an arrangement of panes within the application-frame's top-level win- 
dow. An application may have many layouts or it may have only one layout that re- 
mains constant for the life of the program. If you do not specify any layout, CLIM 
will construct a default layout for the application. 

As the application is running, the current layout may be changed to any of the 
layouts described in the rlayouts option of the frame definition. See the generic 
function climrframe-current-layout. 

The rlayouts option specifies and names the layouts of the application. A layout 
typically consists of rows, columns, and tables of panes, or more complicated nest- 
ings of rows, columns and tables. The value of the rlayouts option is a list of lay- 
out descriptions. Each layout description is a two element list consisting of a sym- 
bol, which names the layout, and a corresponding layout-spec. 
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A layout-spec is a simply a form consisting of the various layout macros that con- 
structs a pane. 

A size-spec can be :fill, rcompute, or a real number between zero and one (exclu- 
sive) (indicating that the size of the pane is that fraction of the available space), 
an integer (indicating that the size of the pane is that many device units), or a 
list whose first element is a real number and whose second element is a "unit" 
(one of :line, rcharacter, :mm, rpoint, or rpixel). 

This syntax can be expressed as follows: 

rlayouts (layout-name layout-panes) 

layout-name is a symbol. 

layout-panes is layout-panesl or (size-spec layout-panesl). 

layout-panesl is a pane-name, or a lay out-macro- form, or layout-code. 

layout-code is Lisp code that generates a pane, which may 
include the name of a named pane. 

size-spec is a positive real number less than 1, or :fill, or 
rcompute. A real number (between zero and one, exclusive) is 
the fraction of the available space to use. rfill means that the 
pane will take as much space as remains when all its sibling panes 
have been given space, rcompute means that the pane's display 
function should be called in order to compute how much space it 
requires. (Note that the display function is run at frame-creation 
time, so it must be able to compute the size correctly at that time.) 

size-spec can also be an integer indicating the size of the pane 
in device units, or a list whose first element is a real number 
and whose second element is a "unit" (one of rline, 
rcharacter, rmm, rpoint, or rpixel). 

layout-macro-form is (layout-macro-name (options) &rest layout-panes). 

layout-macro-name is climrvertically, climrhorizontally, 
climrtabling, climroutlining, climrspacing, or 
climrlabelling. 

The following macros and pane classes provide layout for other panes in CLIM. 

climrvertically f&rest options &key .spacing &allow-other-keys) &body contents 
Lays out one or more child panes vertically, from top to bottom. 

climrvbox-pane 

The layout pane class that arranges its children in a vertical stack. 
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climrhorizontally f&rest options &key .spacing &allow-other-keys) &body contents 
Lays out one or more child panes horizontally, from left to right. 

clim:hbox-pane 

The layout pane class that arranges its children in a horizontal row. 

climrtabling f&rest options) &body contents 

Lays out its child panes in a two-dimensional table arrangement. 

clim:table-pane 

The layout pane class that arranges its children in a tabular format. 

climroutlining f&rest options &key .-thickness &allow-other-keys) &body contents 

Puts an outlined border of the specified thickness around a single child 
pane. 

clim:outlined-pane 

The layout pane class that draws a border around its child pane. 

climrspacing f&rest options &key .-thickness .-background &allow-other-keys) &body 
contents 
Reserves some margin space around a single child pane. 

clim:spacing-pane 

The layout pane class that leaves some empty space around its child 
pane. 

The following macro can be used to label any pane. 

climrlabelling f&rest options &key .-label (.-label-alignment rbottom) &allow-other- 
keysj &body contents 

Creates a vertical stack consisting of two panes, a label and a single oth- 
er pane. 

The following macro can be used to provide scrolling for a pane. 

climrscrolling f&rest options) &body contents 

Creates a composite pane that allows the single child specified by con- 
tents to be scrolled. 



Details of CLIM's Layout Algorithm 

CLIM uses a two pass algorithm to lay out a pane hierarchy. In the first pass 
(called space composition), the top level pane is queried to find out how much 
space it requires. This query may cause the same query to be made, recursively, of 
all the panes in the hierarchy, with the answers being composed to produce the 
top level pane's answer. Each pane answers the query by returning a space require- 
ment (or climrspace-requirement) object, which specifies the pane's desired width 
and height, as well as its willingness to shrink or grow along its width and height. 

In the second pass (called space allocation), the frame manager attempts to obtain 
the required amount of space from the host window system. The top level pane is 
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allocated the space that is actually available. Each pane, in turn, allocates space 
recursively to each of its descendants in the hierarchy according to the pane's 
rules of composition. 

For most types of panes, you can indicate the space requirements of the pane at 
creation time by using the space requirement options (rwidth, rheight, :max-width, 
:min-height, and so on). For example, application panes are used to display appli- 
cation-specific information, so the application can determine how much space 
should normally be given to them. 

Other pane types automatically calculate how much space they need based on the 
information they need to display. For example, push button panes automatically 
calculate their space requirement based on the amount of space required by the 
push button's label. 

A composite pane calculates its space requirement based on the requirements of its 
children and its own particular rule for arranging them. For example, a pane that 
arranges its children in a vertical stack would return as its desired height the 
sum of the heights of its children. Note however that a composite is not required 
by the layout protocol to respect the space requests of its children; in fact, compos- 
ite panes aren't even required to ask their children how big they want to be. 

Space requirements are expressed for each of the two dimensions as a preferred 
size, a minimum size below which the pane cannot be shrunk, and a maximum size 
above which the pane cannot be grown. (The minimum and maximum sizes can al- 
so be specified as relative amounts.) All sizes are specified as a real number indi- 
cating the number of device units (such as pixels). 

The following functions are used in pane layout to compute and allocate space, and 
to set the size and position of the panes. 

clim:make-space-requirement &key (:width 0) (:min-width width) (:max-width 
width) (.-height 0) (:min-height height) (:max-height height) 
Constructs and returns a space requirement object having the given 
components. 

climrspace-requirement-components space-req 

Returns the components of the space requirement space-req as six values, 
the width, minimum width, maximum width, height, minimum height, 
and maximum height. 

clim:space-requirement+ space-req 

Returns a new space requirement whose components are the sum of each 
of the components of srl and sr2. 

clim:compose-space pane &key .-width .-height 

The value returned by clim:compose-space is a space requirement object 
that represents how much space the pane pane requires. 

clim:allocate-space pane width height 

During the space allocation pass, a composite pane will arranges children 
within the available space and allocates space to them according to their 
space requirements and its own composition rules by calling 
clim:allocate-space on each of the child panes. 
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clim:move-sheet sheet x y 

Moves sheet to the new position (x,y). x and y are in coordinates relative 
to sheet's, parent. 

clim:resize-sheet sheet width height 

Changes the size of sheet to have width width and height height. 

clim:move-and-resize-sheet sheet x y width height 

Moves sheet to the new position (x,y), and simultaneously changes the 
size of the sheet to have width width and height height, x and y are in 
coordinates relative to sheet's parent. 



Examples of the rpanes and rlayouts Options to clim:define-application-frame 

Here are some examples of how to use the rpanes and rlayouts options of 
climrdefine-application-frame to describe the appearance of your application. 

We begin by showing an example of how CLIM supplies a default layout when you 
don't explicitly specify one in your frame definition. The default layout is a single 
column of panes, in the order (top to bottom) that you specified them in the 
rpanes option. Command menus are allocated only enough space to display their 
contents, while the remaining space is divided among the other types of panes 
equally. 

(cl im:def ine-appl i cat ion- frame graphics-demo 











(:menu-bar nil) 
( : panes 

(commands : command-menu) 

(demo :appl i cation) 

(explanation :application :scroll-bars nil)))) 



demo 



explanation 




commands 



Figure 64. The default layout for the graphic-demo example when no explicit day- 
out is specified. 
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Now we add an explicit rlayouts option to the frame definition from the previous 
example. The pane named explanation occupies the bottom sixth of the screen. 
The remaining five-sixths are occupied by the demo and commands panes, which 
lie side by side with the command pane to the right. The commands pane is only 
as wide as necessary to display the command menu. 

(cl im:def ine-appl i cat ion- frame graphics-demo 











(:menu-bar nil) 
( : panes 

(commands : command-menu) 
(demo :appl i cation) 

(explanation :application :scroll-bars nil)) 
( : layouts 
(default 

(cl im: vertical ly () 

(5/6 (cl im:horizontal ly () demo commands)) 
(1/6 explanation))))) 



demo 



explanation 




commands 



Figure 65. The layout for the graphic-demo example with an explicit :layout. 

Finally, here is a stripped-down version of the application frame definition for the 
CAD demo (in the file SYS :CLIM;REL-2; DEMO; CAD-DEMO. LISP) which implements an 
extremely simplistic computer-aided logic circuit design tool. 

There are four panes defined for the application. The pane named title displays 
the string "Mini -CAD" and serves to remind the user which application he is using. 
There is a pane named menu which provides a menu of commands for the appli- 
cation. The pane named design-area is the actual "work surface" of the applica- 
tion on which various objects (logic gates and wires) can be manipulated. A pane 
named documentation is provided to inform the user about what actions can be 
performed using the pointing device (typically the mouse) and is updated based on 
what object is pointed to. 

The application has two layouts, one named main and one named other. Both lay- 
outs have their panes arranged in vertical columns. At the top of both layouts is 
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the title pane, which is of the smallest height necessary to display the title string 
"Mini -CAD". Both layouts have the documentation pane at the bottom. 

The two layouts differ in the arrangement of the menu and design-area panes. In 
the layout named main, the menu pane appears just below the title pane and ex- 
tends for the width of the screen. Its height will be computed so as to be suffi- 
cient to hold all the items in the menu. The design-area pane occupies the re- 
maining screen real estate, extending from the bottom of the menu pane to the 
top of the documentation pane, and is as wide as the screen. 

The layout named other differs from the main layout in the shape of the design- 
area pane. Here the implementor of the CAD demo realized that depending on 
what was being designed, either a short, wide area or a narrower but taller area 
might be more appropriate. The other layout provides the narrower, taller alterna- 
tive by rearranging the menu and design-area panes to be side by side (forming a 
row of the two panes). The menu and design-area panes occupy the space between 
the bottom of the title pane and the top of the documentation pane, with the 
menu pane to the left and occupying as much width as is necessary to display all 
the items of the menu and the design-area occupying the remaining width. 

(def ine-appl i cation-frame cad-demo 

(standard-appl ication-f rame output-record) 
((object-list :initform nil)) 
(:menu-bar nil) 
( :pointer-documentation t) 
( : panes 

(title :title :display-string "Mini-CAD") 
(menu : command-menu) 
(design-area :appl i cation)) 
( : layouts 
(default 

(cl im: vertical ly () 
title menu design-area)) 
(other 

(cl im: vertical ly () 
title 
(cl im:horizontal ly () menu design-area))))) 



Using an : accept- values Pane in a CLIM Application Frame 

: accept- values panes are used when you want one of the panes of your application 
to be in the form of an climraccepting-values dialog. 

There are several things to remember when using an : accept- values pane in your 
application frame: 

• For an : accept- values pane to work your frame's command table must inherit 
from the clim:accept-values-pane command table. 
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title 




documentation 

Figure 66. The two layouts of the Mini-CAD demo. Layout main is on the left, 
layout other is on the right. 

• The : display-function option for an : accepting- values pane will typically be 
something like 

(cl i m : accept- val ues-pane-di spl ayer 
:displayer ray-acceptor-function) 

where my -acceptor-function is a function that you write. It contains calls to 
climraccept just as they would appear inside a climraccepting-values for a dia- 
log. It takes two arguments, the frame and a stream, my-acceptor-function 
doesn't need to call climraccepting-values itself, since that is done automatical- 

ly. 

See the section "Menus and Dialogs in CLIM", and see the function climraccept- 
values-pane-displayer. 



Initializing CLIM Application Frames 

There are several ways to initialize an application frame: 



1. The value of an application frame's slot can be initialized using the rinitform 
slot option in the slot's specifier in the climrdefine-application-frame form. 
This technique is suitable if the slot's initial value does not depend on the 
values of other slots, calculations based on the values of initialization argu- 
ments, or other information which can not be determined until after the ap- 
plication frame is created. See the macro closrdefclass to learn about slot- 
specifiers. 
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2. For initializations which depend on information which may not be available 
until the application frame has been created, an rafter method can be defined 
for closrinitialize-instance on the application frame's class. Note that the 
special variable climr*application-frame* is not bound to the application 
since the application is not yet running. You may use closrwith-slots, 
closrwith-accessors, or any slot readers or accessors which have been defined. 

3. A rbefore or raround method for clim:run-frame-top-level on the applica- 
tion's frame is probably the most versatile place to perform application frame 
initialization. This method will not be executed until the application starts 
running. climr*application-frame* will be bound to the application frame. 

4. If the application frame employs its own top-level function, then this function 
can perform initialization tasks at the beginning of its body. This top-level 
function may call clim:default-frame-top-level to achieve the standard behav- 
ior for application frames. 

Of course, these are only suggestions. Other techniques might be more appropriate 
for your application. Of those listed, the rbefore or raround method on climrrun- 
frame-top-level is probably the best for most circumstances. 

Although application frames are CLOS classes, do not use closrmake-instance to 
create them. To instantiate an application frame, always use climrmake- 
application-frame. This function provides important initialization arguments spe- 
cific to application frames which closrmake-instance does not. climrmake- 
application-frame passes any keyword value pairs which it does not handle itself 
on to closrmake-instance. Thus, it will respect any initialization options which you 
give it, just as closrmake-instance would. 

Here is an example of how an application frame's behavior might be modified by 
inheritance from a superclass. 

Suppose we wanted our application to record all of the commands which were per- 
formed while it was executing. This might be useful in the context of a program 
for the financial industry where it is important to keep audit trails for all transac- 
tions. As this is a useful functionality that might be added to any of a number of 
different applications, we will separate it out into a special class which implements 
the desired behavior. This class can then be used as a superclass for any applica- 
tion which should keep a log of its actions. 

The class has an initialization option rpathname which specifies the name of the 
log file. It has a slot named transaction-stream whose value is a stream opened 
to the log file when the application is running. 

(defclass transaction-recording-mixin () 

((transaction-pathname :type pathname 

initarg : pathname 
reader transaction-pathname) 
(transaction-stream : accessor transaction-stream))) 
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We use an raround method on clim:run-frame-top-level which opens a stream to 
the log file, and stores it in the transaction-stream slot, unwind-protect is used 
to clear the value of the slot when the stream is closed. 

(defmethod cl im: run-f rame-top-level : around 

((frame transact ion- record ing-mixin)) 
(with-slots (transaction-pathname transaction-stream) frame 
(with-open-f ile (stream transaction-pathname 

:direction :output) 
(unwind-protect 
(progn 

(setq transaction-stream stream) 
(cal 1 -next-method) ) 
(setq transaction-stream nil))))) 

This is where the actual logging takes place. The command loop in climrdefault- 
frame-top-level calls clinirexecute-franie-conimand to execute a command. Here 
we add a rbefore method which will log the command. 

(defmethod cl im: execute-frame-command : before 

((frame transaction-recording-mixin) command) 
(format (transaction-stream frame) 
"~&Command: ~a" command)) 

It is now an easy matter to alter the definition of an application to add the com- 
mand logging behavior. Here is the definition of the puzzle application frame from 
the CLIM demos suite (from the file SYS :CLIM;REL-2; DEMO; PUZZLE. LISP). Our modifi- 
cations are shown in italics. We use the superclasses argument to specify that the 
puzzle application frame should inherit from transaction-recording-mixin. Be- 
cause we are using the superclass argument, we must also explicitly include 
clim:standard-application-frame, which would be included by default when the 
superclasses argument is empty. 

(def ine-appl ication-f rame puzzle 

(transaction-recording-mixin standard-application-frame) 
((puzzle :initform (make-array '(4 4)) 
: accessor puzzle-puzzle)) 
Odefault-initargs .-pathname "puzzle-log.text") 
( : panes 



(display 



appl i cation 

display-function 'draw-puzzle 

text-style '(:fix :bold :very-large) 

incremental-redisplay t 

text-cursor nil 

width :compute :height :compute 

end-of-page-action : allow 

end-of-1 ine-action :allow)) 



( : layouts 

(:default display))) 



Also note the use of 
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( :defaul t-initargs :pathname "puzzle-log. text") 

to provide a default value for the log file name if the user doesn't specify one. 

The user might run the application by evaluating the following: 

(cl im : run-f rame-top-1 evel 

(cl im:make-appl i cat ion- frame 'puzzle 
:parent (cl im: find-port) 
: pathname "my-puzzl e-1 og . text" ) ) 

Here the rpathname initialization argument was used to override the default name 
for the log file (as was specified by the rdefault-initargs clause in the above appli- 
cation frame definition) and to use the name "my-puzzl e-1 og. text" instead. 

Accessing Slots and Components of CLIM Application Frames 

CLIM application frames are instances of the defined subclass of the 
clim:standard-application-frame class. You explicitly specify accessors for the 
slots you have specified for storing application-specific state information, and use 
those accessors as you would for any other CLOS instance. Other CLIM defined 
components of application frame instances are accessed via documented functions. 
Such components include frame panes, command tables, top-level window, and lay- 
outs. 

Running a CLIM Application 

This section describes how to use CLIM application frames in Cloe Runtime and in 
Genera, but the technique is similar on most platforms. For more information on 
how to run CLIM in these environments, see the section "Using Symbolics CLIM". 

Genera 

In Genera and in Cloe Developer the recommended way to run CLIM applications 
is to make them available to the Genera activity selection system. Call 
climrdefine-genera-application after clim:define-application-frame. 

climrdefine-genera-application frame-name &rest keys &key :pretty-name .select-key 
deft stop .-right .-bottom .-width .-height 

Makes a CLIM application available to the Select Activity command and 
optionally to the SELECT key. This exists only in Genera. 

Cloe Runtime 

In Cloe Runtime clim:define-application-frame automatically does a cloerdefine- 
program. When you call cloersave-program with the name of your application 
frame, it saves a virtual memory image that will run your application when it is 
started. For test purposes, you can use the rsimulate argument to cloersave- 
program to run the program without saving it. 
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Programmatic Ways to Run CLIM Applications 

You can also run a CLIM application using the functions climrmake-application- 
frame and clim:run-frame-top-level. First use clim:find-port to create a port to 
pass as the rparent argument to clim:make-application-frame. Here is a code 
fragment which illustrates this technique under Genera: 

(cl im : run-f rame-top-1 evel 

(cl im:make-appl i cat ion- frame 'frame-name 

:parent (cl im: find-port :server-path ' (:genera)))) 

clim:run-frame-top-level will not return until the application exits. 

Note that clim:*application-frame* is not bound until clim:run-frame-top-level is 
invoked. 

For more information, see the section "Functions for Operating on Windows Di- 
rectly". 



Examples of CLIM Application Frames 

These are examples of how to use CLIM application frames. For other examples, 
see the section "CLIM Tutorial" and see the section "Using the CLIM Demos". 

Example of defining a CLIM application frame 

Here is an example of an application frame. This frame has three slots, named 
pathname, integer and member. It has two panes, an : accept- values pane named 
aw and an : application pane named display. It uses a command table named 
dingus, which will automatically be defined for it (see 
clim:define-command-table) and which inherits from the clim:accept-values-pane 
command table so that the accept-values pane will function properly. 

(cl im:def ine-appl ication-f rame dingus () 
((pathname :initform #p"foo") 
(integer :initform 10) 
(member :initform :one)) 
( : panes 
(aw : accept-values 

: display- function ' (cl im:accept-values-pane-displayer 

:displayer display-aw)) 
(display application 

:display-function 'draw-display 
: di spl ay-after-commands : no-cl ear) ) 
(: command-table (dingus : inherit-f rom (cl im:accept-values-pane)))) 

This is the display function for the display pane of the dingus application. It just 
prints out the values of the three slots defined for the application. 
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(defmethod draw-display ((frame dingus) stream) 
(with-slots (pathname integer member) frame 
(fresh-line stream) 

(cl im:present pathname 'pathname :stream stream) 
(write-string ", " stream) 

(cl im:present integer 'integer :stream stream) 
(write-string ", " stream) 

(cl im: present member '(member :one :two : three) : stream stream) 
(write-string "." stream))) 

This is the display function for the pane named aw. It invokes climraccept for 
each of the application's slots so that the user can alter their values in the aw 
pane. 

(defmethod display-aw ((frame dingus) stream) 
(with-slots (pathname integer member) frame 
(fresh-line stream) 
(setq pathname (clim:accept 'pathname 

: prompt "A pathname" : default pathname 
: stream stream)) 
(fresh-line stream) 
(setq integer (clim:accept 'integer 

: prompt "An integer" : default integer 
: stream stream)) 
(fresh-line stream) 
(setq member (dim: accept '(member :one :two : three) 

:prompt "One, Two, or Three" :default member 
: stream stream)) 
(fresh-line stream) 

(cl im:accept-values-command-button (stream : documentation "You wolf") 
(write-string "Wolf whistle" stream) 
(beep)))) 

This function will start up a new dingus application. The argument is a port, such 
as one returned by clim:find-port. 

(defun run-dingus (port) 

(let ((dingus (cl im:make-appl ication-f rame 'dingus 

:parent port :width 400 :height 400))) 
(cl im: run- frame- top- level dingus))) 

All this application does is allow the user to alter the values of the three applica- 
tion slots pathname, integer and member using the dialog pane, aw. The new 
values will automatically be reflected in the display pane. 

Example of constructing a function as part of running an application 

You can supply an alternate top level (which initializes some things and then calls 
the regular top level) to construct a function as part of running the application. 
Note that when you use this technique, you can close the function over other 
pieces of the Lisp state that might not exist until application runtime. 
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(cl im:def ine-appl ication-f rame different-prompts () 
((prompt-state ...) ...) 
( : top-1 evel (di f f erent-prompts-top-1 evel ) ) 

(defmethod di ff erent-prompts-top-1 evel 

((frame different-prompts) &rest options) 
(flet ((prompt (stream frame) 

(with-slots (prompt-state) frame 

■■■))) 
(apply #'cl im: default- frame- top- level 

frame :prompt ^'prompt options))) 



Operators for Defining CLIM Application Frames 

The following operators are used to define and instantiate CLIM application 
frames, climrdefine-genera-application may only be used under Genera. 

climrdefine-application-frame name superclasses slots &rest options 

Defines a frame and CLOS class named name that inherits from super- 
classes and has state variables specified by slots. 

climrmake-application-frame frame-name &key .-frame-class :pretty-name -.parent 
-.left :top -.right -.bottom -.height -.width &allow-other-keys 
Makes an instance of the application frame of type frame-class. The key- 
word arguments are passed as additional arguments to closrmake- 
instance. 

climrfind-application-frame frame-name &rest initargs &key (-.create t) (.-activate t) 
(■own-process t) sport .-frame-manager .-frame-class &allow-other-keys 
Calling this function is similar to calling climrmake-application-frame, 
and then calling clim:run-frame-top-level on the newly created frame. 

climrdefine-genera-application frame-name &rest keys &key :pretty-name -.select-key 
-.left :top -.right -.bottom -.width -.height 

Makes a CLIM application available to the Select Activity command and 
optionally to the SELECT key. This exists only in Genera. 



CLIM Application Frame Accessors 

The following functions may be used to access state of the application frame itself, 
such as what the currently exposed panes are, what the current layout is, what 
command table is being used, and so forth. 

clim:*application-frame* 

The current application frame. 

climrwith-application-frame (frame) &body body 

Evaluates body with the variable frame bound to the current application 
frame. 
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clim:frame-name frame 

Returns the name of frame. 

clim:frame-pretty-name frame 

Returns the pretty name of frame. 

clim:frame-standard-input frame 

Returns the value that should be used for *standard-input* for frame. 

climrframe-standard-output frame 

Returns the value that should be used for *standard-output* for frame. 

clim:frame-error-output frame 

Returns the value that should be used for *error-output* for frame. 

clim:frame-query-io frame 

Returns the value that should be used for *query-io* for frame. 

climrframe-pointer-documentation-output frame 

Returns the value that should be used for clim:*pointer-documentation- 
output* for frame. 

climrframe-current-layout frame 

Returns the name of current layout for frame. You can use setf on 
climrframe-current-layout to change the current layout. 

clim:frame-all-layouts frame 

Returns a list of all of the layout names for frame. 

climrframe-current-panes frame 

Returns a list of all of the named CLIM stream panes that are contained 
in the current layout for the frame frame. 

climrframe-panes frame 

Returns the single pane acting as the "root" pane for the current lay- 
out. 

clim:get-frame-pane frame pane-name &key (serrorp t) 

Returns the CLIM stream pane named by pane-name in frame. 

clim:find-pane-named frame pane-name &optional errorp 

Returns the CLIM stream pane named by pane-name in frame. 

clim:frame-command-table frame 

Returns the name of the command table currently being used by the 
frame frame. You can use this function with setf to specify the command 
table to be used. 

climrframe-maintain-presentation-histories frame 

Returns t if the frame maintains histories for its presentations, other- 
wise returns nil. The default method on the class climrstandard- 
application-frame returns t if and only if the frame has an interactor 
pane. You can specialize this generic function for your own application 
frames. 
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clim:frame-top-level-sheet frame 

Returns the window that corresponds to the top level window for the 
frame frame. 

clim:frame-state frame 

Returns one of renabled, rdisabled, rdisowned, or rshrunk, indicating 
the current state of frame. 



Operators on CLIM Application Frames 

The following functions are used to start up an application frame, exit from it or 
destroy it, and control the "read-eval-print" loop of the frame (for example, redis- 
play the panes of the frame, and read, execute, enable, and disable commands). 

clim:run-frame-top-level frame &key &allow-other-keys 
Runs the top-level function for frame. 

clim:default-frame-top-level frame &key .-command-parser xommand-unparser :par- 
tial-command-parser (.-prompt "Command: ") 

The default top-level function for application frames, which provides a 
"read-eval-print" loop. 

clim:enable-frame frame 

Enables the application frame frame and changes the state of the frame 
to renabled. 

clim:frame-exit frame 

Exits from the application frame frame by signalling a clim:frame-exit 
condition. 

clim:raise-frame frame 

Raises the application frame frame so that it is on top of all of the other 
host windows by calling clim:raise-sheet on the frame's top-level sheet. 

clim:bury-frame frame 

Buries the application frame frame so that it is underneath all of the 
other host windows. 

clim:destroy-frame frame 

Disables the application frame frame, and then destroys it by deallocat- 
ing all of its CLIM resources and disowning it from its frame manager. 

clim:map-over-frames function &key sport .-frame-manager 

Applies function to all of the application frames that "match" .-port and 
.-frame-manager, function is a function of one argument, the frame. 

clim:display-command-menu frame stream &key .-command-table :max-width :max- 
height :n-rows :n-columns (:cell-align-x 'rleftj (:cell-align-y ':top) 
Displays the menu described by the command table associated with the 
application frame frame onto stream. Disabled items in the menu will be 
"grayed out". 
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clim:accept-values-pane-displayer frame pane &key :displayer :resynchronize-every- 
pass (icheck-overlapping t) :align-prompts :max-height :max-width 
When you use an : accept- values pane, the display function must use 
clim:accept-values-pane-displayer. 

clim:redisplay-frame-pane frame pane-name &key :force-p 

Causes the pane pane-name of frame to be redisplayed immediately. 

clim:redisplay-frame-panes frame &key force-p 

Causes all of the panes of frame to be redisplayed immediately. 

climrframe-replay frame stream &optional region 

Replays all of the output records in stream's, output history on behalf of 
the application frame frame that overlap the region region. 

clim:read-frame-command frame &key .stream 

clim:read-frame-command reads a command from the user on the 
stream .stream, and returns the command object, frame is an application 
frame. You can specialize this generic function for your own application 
frames, for example, if you want to have your application be able to read 
commands using keystroke accelerators. 

clim:execute-frame-command frame command 

clim:execute-frame-command executes the command command on behalf 
of the application frame frame. You can specialize this function if you 
want to change the behavior associated with the execution of commands. 

climrcommand-enabled command-name frame &optional command-table 

Returns t if the command named by command-name is presently enabled 
in command-table for the frame frame, otherwise returns nil. You can 
use setf on climrcommand-enabled in order to enable or disable a com- 
mand. 

clim:command-menu-enabled command-table frame 

Returns t if the command table command-table is presently enabled in 
the command menu for the frame frame, otherwise returns nil. This 
function is like climrcommand-enabled, except that it operates only on 
the rmenu items in a command table's menu for a particular frame. 



Using Gadgets in CLIM 

CLIM supports the use of gadgets as panes within an application. The following 
sections describe the basic gadget protocol, and the various gadgets supplied by 
CLIM. 



Basic Gadget Protocol in CLIM 

Gadgets are panes that implement such common toolkit components as push but- 
tons or scroll bars. Each gadget class has a set of associated generic functions 
that serve the same role that callbacks serve in more traditional toolkits. For ex- 
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ample, a push button has an "activate" callback function that is invoked by CLIM 
when the user "presses" the button; a scroll bar has a "value changed" callback 
that is invoked by CLIM after the user moves its indicator. (Note that user code 
will rarely, if ever, call a callback function itself.) 

The gadget definitions specified by CLIM are abstract, that is, the gadget defini- 
tion does not specify the exact user interface of the gadget, but only specifies the 
semantics that the gadget should provide. For instance, it is not defined whether 
the user clicks on a push button with the mouse or moves the mouse over the but- 
ton and then presses some key on the keyboard to invoke the "activate" callback. 
The user can control some high-level aspects of the gadgets, but each toolkit im- 
plementation will specify the exact "look and feel" of their gadgets. Typically, the 
look and feel will be derived directly from the underlying toolkit. 

Every gadget has an id and a client, which are specified when the gadget is creat- 
ed. The client is notified via the callback mechanism when any important user in- 
teraction takes place. Typically, a gadget's client will be an application frame or a 
composite pane. Each callback generic function is invoked on the gadget, its client, 
the gadget id (described below), and other arguments that vary depending on the 
callback. 

For example, the climractivate-callback takes three arguments, a gadget, the 
client, and the gadget-id. Assuming the programmer has defined an application 
frame called button-test that has a CLIM stream pane in the slot output-pane, he 
could write the following method: 

(defmethod cl im : acti vate-cal 1 back 

((button cl im: push-button) (client button-test) gadget-id) 
(with-slots (output-pane) client 

(format output-pane "The button ~S was pressed, client ~S, id ~S." 
button client gadget-id))) 

One problem with this example is that it differentiates on the class of the gadget, 
not on the particular gadget instance. That is, the same method will run for every 
push button that has the button-test frame as its client. 

One way to distinguish between the various gadgets is via the gadget id, which is 
also specified when the gadget is created. The value of the gadget id is passed as 
the third argument to each callback generic function. In this case, if we have two 
buttons, we might install start and stop as the respective gadget ids and then use 
eql specializers on the gadget ids. We could then refine the above as: 

(defmethod cl im : acti vate-cal 1 back 

((button cl im: push-button) (client button-test) (gadget-id (eql 'start))) 
(start-test client)) 

(defmethod cl im : acti vate-cal 1 back 

((button cl im: push-button) (client button-test) (gadget-id (eql 'stop))) 
(stop-test client)) 
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; ; Create the start and stop push buttons 
(cl im: make-pane 'cl im: push-button 

: label "Start" 

:client frame :id 'start) 
(cl im: make-pane 'cl im: push-button 

: label "Stop" 

:client frame :id 'stop) 

Still another way to distinguish between gadgets is to explicitly specify what func- 
tion should be called when the callback is invoked. This is specified when the gad- 
get is created by supplying an appropriate initarg. The above example could then 
be written as follows: 

;; No callback methods needed, just create the push buttons 
(cl im: make-pane 'cl im: push-button 

: label "Start" 

:client frame 

: acti vate-cal 1 back 
#' (lambda (gadget) (start-test (gadget-client gadget)))) 
(cl im: make-pane 'cl im: push-button 

: label "Stop" 

:client frame 

: acti vate-cal 1 back 

#' (lambda (gadget) (stop-test (gadget-client gadget)))) 

The following classes and functions constitute the basic protocol for all of CLIM's 
gadgets. See the section "Abstract Gadgets in CLIM". 

climrgadget 

The protocol class that corresponds to a gadget. 

climrbasic-gadget 

The implementation class on which many CLIM gadgets are built. 

clim:gadget-id gadget 

Returns the gadget id of the gadget gadget. 

climrgadget-client gadget 

Returns the client of the gadget gadget. 

climrarmed-callback gadget client id 

The callback that is invoked when the gadget gadget is armed. 

climrdisarmed-callback gadget client id 

The callback that is invoked when the gadget gadget is disarmed. 

climractivate-gadget gadget 

Causes the gadget to become active, that is, available for input. 

climrdeactivate-gadget gadget 

Causes the gadget to become inactive, that is, unavailable for input. 
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clim:gadget-active-p gadget 

Returns t if the gadget is active, that is, available for input. Otherwise, 
it returns nil. 

climrnote-gadget-activated client gadget 

This function is invoked after a gadget is made active. 

climrnote-gadget-deactivated client gadget 

This function is invoked after a gadget is made inactive. 

climrvalue-gadget 

The class used by gadgets that have a value. 

clim:gadget-value gadget 

Returns the value of the gadget value-gadget. You can use setf on 
clim:gadget-value to change the value of a gadget. 

climrvalue-changed-callback gadget client id value 

The callback that is invoked when the value of a gadget is changed, ei- 
ther by the user or programatically. Generally, this function will call an- 
other programmer-specified callback function. 

climrdrag-callback gadget client id value 

The callback that is invoked when the value of a slider or scroll bar is 
changed while the indicator is being dragged. Generally, this function 
will call another programmer-specified callback function. 

climraction-gadget 

The class used by gadgets that perform some kind of action, such as a 
push button. 

climractivate-callback gadget client id 

The callback that is invoked when the gadget is activated. 

cliniroriented-gadget-mixin 

The class that is mixed in to a gadget that has an orientation associated 
with it, for example, a slider. 

climrgadget-orientation oriented-gadget 

Returns the orientation of the gadget oriented-gadget. Typically, this will 
be a keyword such as rhorizontal or rvertical. 

clim:labelled-gadget-mixin 

The class that is mixed in to a gadget that has a label, for example, a 
push button. 

clim:gadget-label labelled-gadget 

Returns the label of the gadget labelled-gadget. 

clinirrange-gadget-mixin 

The class that is mixed in to a gadget that has a range, for example, a 
slider. 

clim:gadget-min-value range-gadget 

Returns the minimum value of the gadget range-gadget. 
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clim:gadget-max-value range-gadget 

Returns the maximum value of the gadget range-gadget. 



Abstract Gadgets in CLIM 

Gadgets such as push buttons and sliders in CLIM are called abstract gadgets. 
This is because the classes, such as climrpush-button and climrslider, do not 
themselves implement gadgets, but rather arrange for the frame manager layer of 
CLIM to create concrete gadgets that correspond to the abstract gadgets. The call- 
back interface to all of the various implementations of the gadget is defined by the 
abstract class. In the rpanes clause of clim:define-application-frame, the abbrevi- 
ation for a gadget is the name of the abstract gadget class. 

At pane creation time (that is, during clim:make-pane), the frame manager re- 
solves the abstract class into a specific implementation class; the implementation 
classes specify the detailed look and feel of the gadget. Each frame manager will 
keep a mapping from abstract gadgets to an implementation class; if the frame 
manager does not implement its own gadget for the abstract gadget classes in the 
following sections, it should use the portable class provided by CLIM. Since every 
implementation of an abstract gadget class is a subclass of the abstract class, they 
all share the same programmer interface. 

The following classes and functions comprise CLIM's abstract gadgets. See the sec- 
tion "Basic Gadget Protocol in CLIM". 

clim:make-pane pane-class &rest pane-options 

Selects a class that implements the behavior of the abstract pane pane- 
class and constructs a pane of that class. 

climrpush-button 

The gadget class that provides press-to-activate switch behavior. 

climrtoggle-button 

The gadget class that provides "on/off" switch behavior. 

clim:radio-box 

A gadget that constrains one or more toggle buttons. At any one time, 
only one of the buttons managed by the radio box may be "on". 

clim:check-box 

Like a radio box: this gadget constrains one or more toggle buttons. At 
any one time, zero or more of the buttons managed by the check box 
may be "on". 

clim:with-radio-box f&rest options &key (:type ':one-ofj &allow-other-keysJ &body 
body 

Creates a radio box or a check box whose buttons are created by the 
forms in body. 

clim:list-pane 

The gadget class that corresponds to a pane whose semantics are similar 
to a radio box or check box, but whose visual appearance is a list of 
buttons. 
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clim:option-pane 

The gadget class that corresponds to a pane whose semantics are identi- 
cal to a list pane, but whose visual appearance is a single push button 
which, when pressed, pops up a menu of selections. 

clim:scroll-bar 

The gadget class that corresponds to a scroll bar. The usual interface to 
creating a scroll bar is to use the climrscrolling macro. 

climrslider 

The gadget class that corresponds to a slider. 

clim:text-field 

The gadget class that implements a text field. The value of a text field 
is the text string. 

climrtext-editor 

The gadget class corresponds to a multi-line field containing text. The 
value of a text editor is the text string. 

Example of an Application That Uses Gadgets 

The following is an example of the frame definition of an application frame that 
uses several different gadgets. 

(defclass color-chooser-pane (cl im:cl im-stream-pane) ()) 

(defmethod cl im: handle-repaint :after ((stream color-chooser-pane) region) 
(declare (ignore region)) 
(display-color (cl im: pane-frame stream) stream)) 

(cl im:def ine-appl ication-f rame color-chooser () 
(color 

red blue green 
intensity hue saturation) 
(:menu-bar nil) 
( : panes 

(display (cl im:make-cl im-stream-pane 
:type 'color-chooser-pane 
: scroll -bars nil 

: display-function 'display-color 

;; Make sure we don't have a useless cursor blinking away... 
: initial-cursor-visibil ity nil)) 
(exit cl im: push-button 
: label "Exit" 
:activate-cal lback ft' (lambda (button) 
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(cl im: frame-exit (cl im: pane-frame button)))) 
(rgb (with-slots (red green blue) cl im:*appl ication-f rame* 
(cl im:outl ining () 
(cl im:horizontal ly () 

(setq red (cl im: make-pane dim: 'slider 

: label "Red" foreground clim:+red+ 
:orientation vertical 
:min-value 0.0 :max-value 1.0 
:show-value-p t :decimal-places 3 
:client 'color :id 'red)) 
(setq green (cl im: make-pane 'clim:slider 

: label "Green" foreground clim:+green+ 
:orientation vertical 
:min-value 0.0 :max-value 1.0 
:show-value-p t :decimal-places 3 
:client 'color :id 'green)) 
(setq blue (make-pane 'clim:slider 

: label "Blue" foreground clim:+blue+ 
:orientation vertical 
:min-value 0.0 :max-value 1.0 
:show-value-p t :decimal-places 3 
:client 'color :id 'blue)))))) 
(ihs (with-slots (intensity hue saturation) cl im:*appl ication-f rame* 
(cl im:outl ining () 
(cl im:horizontal ly () 

(setq intensity (cl im:make-pane 'clim:slider 
: label "Intensity" 
:orientation vertical 
:min-value 0.0 :max-value (sqrt 3) 
:show-value-p t :decimal-places 3 
:client 'color :id 'intensity)) 
(setq hue (cl im:make-pane 'clim:slider 
: label "Hue" 
:orientation vertical 
:min-value 0.0 :max-value 1.0 
:show-value-p t :decimal-places 3 
:client 'color :id 'hue)) 
(setq saturation (cl im:make-pane 'clim:slider 
:label "Saturation" 
:orientation vertical 
:min-value 0.0 :max-value 1.0 
:show-value-p t :decimal-places 3 



Page 1369 



:client 'color :id 'saturation))))))) 
( : layouts 
(default 

(cl im:horizontal ly () 
(cl im:outl ining () 

(cl im: vertical ly () display exit)) 
rgb ins)))) 

(defmethod cl im: run-frame-top-level : before ((frame color-chooser) &key) 
(with-slots (color) frame 
(setf color cl im:+black+))) 

(defmethod color ((frame color-chooser)) 
(with-slots (color) frame 
color)) 

(defmethod (setf color) (new-color (frame color-chooser)) 
(with-slots (color) frame 
(setf color new-color))) 

(defmethod display-color ((frame color-chooser) stream) 
(cl im:with-bounding-rectanglex (left top right bottom) 
(cl im:window-viewport stream) 
(cl im:with-output-recording-options (stream : record nil) 
(cl im:draw-rectanglex stream left top right bottom 

:filled t :ink (slot-value frame 'color))))) 

(defmacro def ine-rgb-cal lbacks (color) 

(check-type color (member red green blue)) 
(let* ((rgb '(red green blue)) 

(new-rgb (substitute 'value color rgb))) 
1 (progn 

(defmethod cl im: value-changed-cal lback 
((si ider cl im:sl ider) 
(client (eql 'color)) (id (eql ', color)) value) 
(let ((frame (cl im: pane-frame slider))) 

(multiple-value-bind (,@rgb) (cl im:color-rgb (color frame)) 
(declare (ignore , color)) 
(setf (color frame) (cl im:make-rgb-color ,@new-rgb))) 
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(update-ihs frame))) 
(defmethod cl im:drag-cal lback 

((si ider cl im:sl ider) 
(client (eql 'color)) (id (eql ', color)) value) 
(let ((frame (cl im: pane-frame slider))) 

(multiple-value-bind (,@rgb) (cl im:color-rgb (color frame)) 
(declare (ignore , color)) 

(setf (color frame) (cl im:make-rgb-color ,@new-rgb))) 
(update-ihs frame)))))) 

(def ine-rgb-cal 1 backs red) 
(def ine-rgb-cal lbacks green) 
(def ine-rgb-cal lbacks blue) 

(defmethod update-ihs ((frame color-chooser)) 
(with-slots (intensity hue saturation) frame 

(multiple-value-bind (ii hh ss) (cl im:color-ihs (color frame)) 
(setf (cl im: gadget-value intensity : invoke-cal lback nil) ii) 
(setf (cl im: gadget-value hue : invoke-cal lback nil) hh) 
(setf (cl im: gadget-value saturation : invoke-cal lback nil) ss)))) 

(defmacro def ine-ihs-cal lbacks (color) 

(check-type color (member intensity hue saturation)) 
(let* ((ihs '(intensity hue saturation)) 

(new-ihs (substitute 'value color ihs))) 
1 (progn 

(defmethod cl im: value-changed-cal lback 
((si ider cl im:sl ider) 
(client (eql 'color)) (id (eql ', color)) value) 
(let ((frame (cl im: pane-frame slider))) 

(multiple-value-bind (,@ihs) (cl im:color-ihs (color frame)) 
(declare (ignore , color)) 

(setf (color frame) (cl im:make-ihs-color ,@new-ihs))) 
(update-rgb frame))) 
(defmethod cl im:drag-cal lback 

((si ider cl im:sl ider) 
(client (eql 'color)) (id (eql ', color)) value) 
(let ((frame (cl im: pane-frame slider))) 

(multiple-value-bind (,@ihs) (cl im:color-ihs (color frame)) 
(declare (ignore , color)) 

(setf (color frame) (cl im:make-ihs-color ,@new-ihs))) 
(update-rgb frame)))))) 

(def ine-ihs-cal lbacks intensity) 

(def ine-ihs-cal lbacks hue) 

(def ine-ihs-cal lbacks saturation) 
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(defmethod update-rgb ((frame color-chooser)) 
(with-slots (red green blue) frame 

(multiple-value-bind (rr gg bb) (cl im:color-rgb (color frame)) 
(setf (cl im: gadget-value red : invoke-cal lback nil) rr) 
(setf (cl im: gadget-value green : invoke-cal lback nil) gg) 
(setf (cl im: gadget-value blue : invoke-cal lback nil) bb)))) 

(defmethod cl im: value-changed-cal lback :after 

((slider clim:slider) (client (eql 'color)) id value) 
(declare (ignore id value)) 
(let ((frame (cl im: pane-frame slider))) 

(redi splay-frame-pane (pane-frame slider) 'display))) 



Commands in CLIM 



Introduction to CLIM Commands 

In CLIM, users interact with applications through the use of commands. Com- 
mands are a way of representing an operation in an application. 

Commands are performed by the command loop, which accepts input of presenta- 
tion type climrcommand and then executes the accepted command. "Command Ob- 
jects in CLIM" discusses how commands are represented. 

CLIM also supports actions which are performed directly by the user interface. Ac- 
tions are seldom necessary, as it is usually the functionality of commands which is 
desired. See the macro climrdefine-presentation-action for a discussion about the 
appropriateness of presentation actions. 

CLIM supports four main styles of interaction: 

• Mouse interaction via command menus. A command is invoked by clicking on an 
item in a menu. 

• Mouse interaction via command translators, including direct manipulation 
("drag and drop") interactions. A command can be invoked by clicking on any 
object displayed by the interface. The particular combination of mouse-buttons 
and modifier keys (such as shift or control) is called a gesture. As part of the 
presentation system, a command translator turns a gesture on an object into a 
command. 

• Keyboard interaction using a command-line processor. The user types a complete 
textual representation of command names and arguments. The text is parsed by 
the command-line processor to form a command. A special character (usually 
Newline) indicates to the command-line processor that the text is ready to be 
parsed. 
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• Keyboard interaction using keystroke accelerators. A single keystroke invokes 
the associated command. 

The choice of interaction styles is independent of the command loop or the set of 
commands, and is entirely under the control of the application programmer. The 
relationship between a user's interactions and the commands to be executed is gov- 
erned by command tables. A command table is an object that serves to mediate be- 
tween a command input context, a set of commands, and these interaction styles. 

Commands may take arguments, which are specified by their presentation types. 

For most CLIM applications, clim:define-application-frame will automatically cre- 
ate a command table, a top level command input context, and define a command 
defining macro for you. 

Following a discussion of the simple approach, this chapter discusses command 
tables and the command processor in detail. This information is provided for the 
curious and for those who feel they require further control over their application's 
interactions. These are some circumstances which might suggest something beyond 
the simple approach: 

• Your application requires more than one command table, for example, if it has 
multiple modes with different sets of commands available in each mode. 

• If you have sets of commands that are common among several modes or even 
among several applications, you could use several command tables and inheri- 
tance to help organize your command sets. 

• Your application may be complex enough that you may want to develop more 
powerful tools for examining and manipulating command tables. 

If you do not require this level of detail, then you can just read "Defining Com- 
mands the Easy Way" and skip the remainder of this chapter. 



Defining Commands the Easy Way 

CLIM provides utilities to make it easy to define commands for most applications. 
clim:define-application-frame will automatically create a command table for your 
application. This behavior is controlled by the :command-table option. It will also 
define a command defining macro which you will use to define the commands for 
your application. This is controlled by the rcommand-definer option. 

This command definer macro will behave similarly to climrdefine-command, but 
will automatically use your application's command table so you needn't specify one. 

Here is an example code fragment illustrating the usage of climrdefine- 
application-frame which defines an application named editor. A command table 
named editor-command-table is defined to mediate the user's interactions with 
the editor application. It also defines a macro named define-editor-command 
which the application programmer will use to define commands for the editor ap- 
plication and install them in the command table editor-command-table. 
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(cl im:def ine-appl ication-f rame editor () 


( : command-tabl e edi tor-command-tabl e) 
( :command-def iner def ine-edi tor-command) 

Note that for this particular example, the :command-table and rcommand-definer 
options need not have been specified, since the names that they specify would be 
the ones which would be generated by default. These options normally are provided 
only when you want different names other than the default ones, you don't want a 
command definer or you want to specify which command tables the application's 
command table inherits from. See the section "Defining Application Frames in 
CLIM" and see the macro clim:define-application-frame for a description of these 
options. 

Command names and command line names 

Every command has a command name, which is a symbol. The symbol names the 
function which implements the command. The body of the command is the function 
definition of that symbol. 

By convention, commands are named with a "com-" prefix, although CLIM does not 
enforce this convention. 

To avoid collisions among command names, each application should live in its own 
package; for example, there might be several commands named com-show-chart 
defined for each of a spreadsheet, a navigation program and a medical application. 

CLIM supports a command line name which is separate from the command's actual 
name. For command line interactions, the end user sees and uses the command 
line name. For example, the command com-show-chart would have a command 
line name of "Show Chart". When defining a command using climrdefine- 
command (or the application's command defining macro), you can have a com- 
mand line name generated automatically. 

The automatically generated command line name consists of the command's name 
with the hyphens replaced by spaces, and the words capitalized; furthermore, if 
there is a prefix of "com-", the prefix is removed. For example, if the command 
name is com-show-file, the command line name will be "Show File". 

The define-editor-command macro, which would automatically be generated by 
the above example fragment, is used to define a command for the editor applica- 
tion, define-editor-command is used in the same way as climrdefine-command. 
However, rather than requiring that the programmer specify editor-command- 
table as the command table in which to define the command, define-editor- 
command will automatically use editor-command-table. 

Through the appropriate use of the options to define-editor-command (the same 
options as for climrdefine-command), the programmer can provide the command 
via any number of the above mentioned interaction styles. For example, you could 
install the command in the editor application's menu as well as specify a single 
keystroke command accelerator for it. 
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This example defines a command whose command name is com-save-file. The 
com-save-file command will appear in the application's command menu, by the 
name "Save File" (which is automatically generated from the command name 
based on the same method as for command line names). The single keystroke con- 
trol -S will also invoke the command. 

(def ine-edi tor-command (com-save-file :menu t 

: keystroke (:s : control)) 


...) 

Here, a command line name of "Save File" is associated with the com-save-file 
command. The user can then type "Save File" to the application's interaction 
pane to invoke the command. 

(def ine-edi tor-command (com-save-file :name "Save File") 


...) 

Since the command processor works by establishing an input context of presenta- 
tion type climrcommand and executing the resulting input, any displayed presenta- 
tion can invoke a command so long as there is a translator defined which trans- 
lates from the presentation type of the presentation to the presentation type 
climrcommand. By this mechanism, the programmer can associate a command 
with a pointer gesture when applied to a displayed presentation, climrdefine- 
presentation-to-command-translator will create such an association. 

clim:define-presentation-to-command-translator name (from-type command-name 
command-table &key (.-gesture 'rselect) .-tester .-documentation .-pointer- 
documentation (:menu t) .-priority (-.echo t)) arglist &body body 
Defines a presentation translator that translates a displayed presentation 
into a command. 

See the section "Making Commands From Presentations" for an example using 
clim:define-presentation-to-command-translator. 



Command Objects in CLIM 

What is a command? 

A command is an object that represents a single user interaction. Each command 
has a command name, which is a symbol. A command can also have arguments, 
both positional and keyword arguments. 

CLIM represents commands as command objects. The internal representation of a 
command object is a cons of the command name and a list of the command's argu- 
ments and is therefore analogous to a Lisp expression. Functions are provided for 
extracting the command name and the arguments list from a command object: 

clim:command-name command 

Given a command object command, returns the command name. 
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climrcommand-arguments command 

Given a command object command, returns the command's arguments. 

It is possible to represent a command for which some of the arguments have not 
yet been specified. The value of the symbol clim:*unsupplied-argument-marker* 
is used in place of any argument which has not yet been specified. 

clim:*unsupplied-argument-marker* 

The value of clim:*unsupplied-argument-marker* serves as a placehold- 
er in a command object for required arguments which have not yet been 
supplied. 

clim:partial-command-p command 

Returns t if the command object command is a partial command, other- 
wise returns nil. 

One can think of climrdefine-command as defining templates for command ob- 
jects. It defines a symbol as a command name and associates with it the presenta- 
tion types corresponding to each of the command's arguments. 

climrdefine-command name arguments &body body 

Defines a command and characteristics of the command, including its 
name, its arguments, and, as options: the command table in which it 
should appear, its keystroke accelerator, its command-line name, and 
whether or not (and how) to add this command to the menu associated 
with the command table. 



CLIM Command Tables 

CLIM command tables are represented by instances of the CLOS class 
climrcommand-table. A command table serves to mediate between a command in- 
put context, a set of commands and the interactions of the application's user. 

Command tables associate command names with command line names. Command 
line names are used in the command line interaction style. They are the textual 
representation of the command name when presented and accepted. 

A command table can describe a menu from which users can choose commands. A 
command table can support keystroke accelerators for invoking commands. 

A command table can have a set of presentation translators and actions, defined by 
climrdefine-presentation-translator, clim:define-presentation-to-command- 

translator, and climrdefine-presentation-action. This allows the pointer to be 
used to input commands, including command arguments. 

We say that a command is present in a command table when it has been added to 
the command table by being associated with some form of interaction. We say that 
a command is accessible in a command table when it is present in the command ta- 
ble or is present in any of the command tables from which the command table in- 
herits. 
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clim:command-table 

The class that represents command tables. 

clim:command-table-name command-table 

Returns the name of the command table command-table. 

clim:command-table-inherit-from command-table 

Returns a list of all of the command tables from which command-table 
inherits. 

clim:find-command-table name &key (:errorp t) 

Returns the command table named by name. 

clim:define-command-table name &key dnherit-from :menu dnherit-menu 
Defines a new command table. 

clim:make-command-table name &key dnherit-from :menu dnherit-menu (:errorp t) 

Creates a command table named name that inherits from dnherit-from 
and has a menu specified by :menu. 

A command table can inherit from other command tables. This allows larger sets 
of commands to be built up through the combination of smaller sets. In this way, a 
tree of command tables can be constructed. During command lookup, if a command 
is not found in the application's command table, then the command tables from 
which that command table inherits are searched also. It is only when the entire 
tree is exhausted that an error is signalled. 

CLIM provides several command tables from which it is recommended that your 
application's command table inherit. See the section "CLIM's Predefined Command 
Tables" for a description of these command tables. 

The macro clim:do-command-table-inheritance is provided as a facility for pro- 
grammers to walk over a command table and the command tables it inherits from 
in the proper precedence order. 

clim:do-command-table-inheritance (command-table-var command-table) &body 
body 

Successively evaluates body with command-table-var bound first to the 
command table command-table, and then to all of the command tables 
from which command-table inherits. 

These functions are provided for examining and altering the commands in a com- 
mand table: 

clim:add-command-to-command-table command-name command-table &key :name 
-.menu -.keystroke (:errorp t) 

Adds the command named by command-name to the command table com- 
mand-table. 

clim:remove-command-from-command-table command-name command-table &key 
Oerrorp t) 

Removes the command named by command-name from the command ta- 
ble command-table. 
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clim:command-present-in-command-table-p command-name command-table 
Returns t if command-name is present in command-table. 

clim:command-accessible-in-command-table-p command-name command-table 
Returns t if command-name is accessible in command-table. 

clim:map-over-command-table-commands function command-table &key (.-inherited 

t) 

Applies function to all of the commands accessible in command-table. 



CLIM's Predefined Command Tables 

CLIM provides these command tables: 

clim:global-command-table 

The "global" command table from which all command tables inherit. 

clim:user-command-table 

A command table reserved for user-defined commands. 

clim:accept-values-pane 

When you use an climraccept-values pane in a climrdefine-application- 

frame, you must inherit from this command table. 

It is recommended that an application's command table inherit from climruser- 
command-table. clim:user-command-table inherits from climrglobal-command- 
table. If your application uses an : accept- values pane, then its command table 
must inherit from the clim:accept-values-pane command table in order for it to 
work properly. 



Conditions Relating to CLIM Command Tables 

Command table operations can signal these conditions: 

clim:command-table-already-exists 

This condition is signalled by clim:make-command-table when you try 
to create a command table that already exists. 

clim:command-table-not-found 

This condition is signalled by functions such as climrfind-command- 
table when the named command table cannot be found. 

clim:command-not-present 

A condition that is signalled when the command you are looking for is 
not present in the command table. 

clim:command-not-accessible 

A condition that is signalled when the command you are looking for is 
not accessible in the command table. 

climrcommand-already-present 

A condition that is signalled when a command is already present in the 
command table. 
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Styles of Interaction Supported by CLIM 

CLIM supports four main styles of interaction: 

• Mouse interaction via command menus. 

• Mouse interaction via translators, including direct manipulation ("drag 
and drop") interactions. 

• Keyboard interaction using a command-line processor. 

• Keyboard interaction using keystroke accelerators. 

See the section "Defining Commands the Easy Way" for a simple description of 
how to use climrdefine-command to associate a command with any of these inter- 
action styles. 

The following subsections describe these interaction styles. 



CLIM's Command Menu Interaction Style 

Each command table may describe a menu consisting of an ordered sequence of 
command menu items. The menu specifies a mapping from a menu name (the 
name displayed in the menu) to either a command object or a submenu. The menu 
of an application's top-level command table may be presented in a window-system 
specific way, for example, as a menu bar, or in a :menu application frame pane. 

These menu items are typically defined using the :menu option to climrdefine- 
command (or the application's command defining macro). 

The following functions can be used to display a command menu in one of the 
panes of an application frame, or to choose a command from a menu. 

clim:display-command-table-menu command-table stream &key :max-width :max- 
height :n-rows :n-columns :x-spacing .y-spacing (:cell-align-x 'rleftj (xell- 
align-y ':top) (.-initial-spacing t) :row-wise :move-cursor 
Displays the menu for command-table on stream. 

clim:display-command-menu frame stream &key : command-table :max-width :max- 
height :n-rows :n-columns (:cell-align-x 'rleftj (:cell-align-y ':top) 
Displays the menu described by the command table associated with the 
application frame frame onto stream. Disabled items in the menu will be 
"grayed out". 

clim:menu-choose-command-from-command-table command-table &key (.-associat- 
ed-window (clim:frame-top-level-window clim:*application-frame*)J 

.-text-style .-label .-cache (:unique-id climrcommand-tablej (:id-test #'eql) 
.-cache-value (-.cache-test #'eql) 

Displays a menu of all of the commands in command-table's menu, and 
waits for the user to choose one of the commands. The returned value is 
a command object. 

A number of lower level functions for manipulating command menus are also pro- 
vided: 
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clim:add-menu-item-to-command-table command-table string type value &key .-doc- 
umentation (:after ':endj .-keystroke .-text-style (:errorp t) 
Adds a command menu item to command-table's menu. 

clim:remove-menu-item-from-command-table command-table string &key (:errorp 
t) 
Removes the item named by string from command-table's menu. 

clim:map-over-command-table-menu-items function command-table 

Applies function to all of the menu items in command-table's menu. 

clim:find-menu-item menu-name command-table &key (:errorp t) 

Given a menu-name and a command-table, return two values, the com- 
mand menu item and the command table in which it was found. 

clim:command-menu-item-type item 

Returns the type of the command menu item item. 

clim:command-menu-item-value item 

Returns the value of the command menu item item. For example, if the 
type of item is rcommand, this will return a command or a command 
name. 

clim:command-menu-item-options item 

Returns a property list of the options for the command menu item item. 

climrcommand-enabled command-name frame &optional command-table 

Returns t if the command named by command-name is presently enabled 
in command-table for the frame frame, otherwise returns nil. You can 
use setf on climrcommand-enabled in order to enable or disable a com- 
mand. 

clim:command-menu-enabled command-table frame 

Returns t if the command table command-table is presently enabled in 
the command menu for the frame frame, otherwise returns nil. This 
function is like climrcommand-enabled, except that it operates only on 
the rmenu items in a command table's menu for a particular frame. 



Mouse Interaction Via Presentation Translators 

A command table maintains a database of presentation translators. A presentation 
translator translates from its from presentation type to its to presentation type when 
its associated pointer gesture (that is, clicking a mouse button) is input. A presen- 
tation translator is triggered when its to presentation type matches the input con- 
text and its from presentation type matches the presentation type of the displayed 
presentation (the appearance of one of your application's objects on the display) on 
which the gesture is performed. 

clim:define-presentation-to-command-translator can be used to associate a pre- 
sentation and a gesture with a command to be performed on the object which the 
presentation represents. 
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Translators can also be used to translate from an object of one type to an object of 
another type based on context. For example, consider an computer aided design 
system for electrical circuits. You might have a translator which translates from a 
resistor object to the numeric value of its resistance. When asked to enter a resis- 
tance (as an argument to a command or for some other query), the user could 
click on the presentation of a resistor to enter its resistance. 

CLIM also supports a drag and drop interaction style via a special kind of presen- 
tation translators that takes into account both a "source" object and a "destina- 
tion" object. For example, an interaction that involves dragging a pathname object 
over a trashcan object might result in a command that causes the specified file to 
be deleted. You can use clim:define-drag-and-drop-translator to define such 
translators. 

For a discussion of the facilities supporting the mouse translator interaction style, 
see the section "Presentation Types in CLIM". 



CLIM's Command Line Interaction Style 

One interaction style supported by CLIM is the command line style of interaction 
provided on most conventional operating systems. A command prompt is displayed 
in the application's rinteractor pane. The user enters a command by typing its 
command line name, followed by its arguments. What the user types (or enters via 
the pointer) is echoed to the interactor window. When the user has finished typing 
the command, it is executed. 

In CLIM, this interaction style is augmented by the input editing facility which al- 
lows the user to correct typing mistakes (see the section "Input Editing and Built- 
in Keystroke Commands in CLIM") and by the prompting and help facilities, which 
provide a description of the command and the expected arguments. Command entry 
is also facilitated by the presentation substrate which allows the input of objects 
matching the input context, both for command names and command arguments. 

See the section "Presentation Types in CLIM" for a detailed description. 

clim:find-command-from-command-line-name name command-table &key (serrorp 

t) 

Given a command-line name name and a command table, this function re- 
turns two values, the command name and the command table in which 
the command was found. 

clim:command-line-name-for-command command-name command-table &key (:er- 
rorp t) 

Returns the command-line name for command-name as it is installed in 
command-table. 

clim:map-over-command-table-names function command-table &key (.-inherited t) 

Applies function to all of the command-line names accessible in com- 
mand-table. 
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CLIM's Keystroke Interaction Style 

Each command table may have a mapping from keystroke accelerators to either 
command objects or submenus. This mapping is similar to that for menu items as 
the programmer might provide a single keystroke equivalent to a command menu 
item. 

Since the kinds of characters that can be typed in vary widely from one platform 
to another, you should be careful in choosing keystroke accelerators. Some sort of 
per-platform conditionalization is to be expected. 

Keystroke accelerators will typically be associated with commands through the use 
of the rkeystroke option to climrdefine-command (or the application's command 
defining macro). 

clim:add-keystroke-to-command-table command-table keystroke type value &key 
documentation (:errorp t) 
Adds a keystroke accelerator to the command-table. 

clim:remove-keystroke-from-command-table command-table keystroke &key (:er- 
rorp t) 

Removes the item named by keystroke from command-table's accelerator 
table, command-table may be either a command table or a symbol that 
names a command table. 

clim:map-over-command-table-keystrokes function command-table 

Applies function to all of the keystroke accelerators in command-table's 
accelerator table. 

clim:find-keystroke-item keystroke command-table &key :test (:errorp t) 

Given a keystroke accelerator keystroke and a command-table, returns two 
values, the command menu item associated with the keystroke and the 
command table in which it was found. 

clim:lookup-keystroke-item keystroke command-table &key :test 

Like clim:find-keystroke-item, except that it descends into sub-menus in 
order to find a keystroke accelerator matching keystroke. 

clim:lookup-keystroke-command-item keystroke command-table &key :test (.-numer- 
ic-argument I) 

Like clim:lookup-keystroke-item, except that it searches only for en- 
abled commands. 

Because of the potential ambiguity between keystroke accelerators and normal 
typed input, the default CLIM command loop does not handle keyboard accelera- 
tors. 

In order to use keystroke accelerators, your application will need to specialize the 
clinirread-franie-conimand generic function. The default method for climrread- 
frame-command just calls climrread-command. You can specialize it to call 
clim:read-command-using-keystrokes within the context of climrwith-command- 
table-key strokes : 
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(defmethod cl im: read-frame-command ((frame my-appl i cation) &key) 
(let ((command-table (cl im: find-command-table 'my-command-table))) 
(cl im:with-command-table-keystrokes (keystrokes command-table) 
(cl im: read-command-us ing-key strokes command- table keystrokes)))) 

clim:with-command-table-keystrokes (keystroke-var command-table) &body body 

Binds keystroke-var to a list that contains all of the keystroke accelera- 
tors in the command table command-table, and then evaluates body in 
that context. 

clim:read-command-using-keystrokes command-table keystrokes &key (.stream 
*query-io*J (: command-parser climr*command-parser*) (xommand- 
unparser climr*command-unparser*) Opartial-command-parser 

climr*partial-command-parser*) 

Reads a command from the user via a command line, the pointer, or typ- 
ing a single keystroke. 

If your application also employs the command line interaction style there is the po- 
tential for ambiguity as to whether a character is intended as command line input, 
a keystroke accelerator, or an input editing command (see the section "Input Edit- 
ing and Built-in Keystroke Commands in CLIM"). For this reason, it is recommend- 
ed that you choose keystroke accelerators that do not conflict with the standard 
printed character set (which might be used for command names and the textual 
representations of arguments) or with the input editor. CLIM will make some at- 
tempt to resolve such conflicts if they arise. A keystroke accelerator can only be 
invoked if there is no other pending command line input. If there is pending input, 
keystroke accelerators will not be considered and the keystroke will be interpreted 
as input or as an input editor command. If there is no pending input, the 
keystroke accelerator behavior will take precedence over that of the input editor. 

The way CLIM processes keystroke accelerators is that clim:stream-read-gesture 
checks to see if keystroke is one of the gestures in climr*accelerator-gestures*. If 
it is, CLIM signals a condition of type climraccelerator-gesture. If you need more 
control over keystroke accelerators than is provided by climrread-command-using- 
keystrokes, you can use the following: 

climr*accelerator-gestures* 

A list of gestures that CLIM will treat as keystroke accelerators when 
reading commands. 

climraccelerator-gesture 

CLIM signals an climraccelerator-gesture condition whenever it reads 
an accelerator gesture from the user. 

climraccelerator-gesture-event accelerator-gesture 

Returns the event object that caused the accelerator gesture condition, 
accelerator-gesture, to be signalled. 

climraccelerator-gesture-numeric-argument accelerator-gesture 

Returns the numeric argument associated with the accelerator gesture 
condition, accelerator-gesture. 
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For a description of the CLIM command processor, see the section "The CLIM 
Command Processor". 



Command Related Presentation Types 

CLIM provides several presentation types pertaining to commands: 

climrcommand &key : command-table 

The presentation type used to represent a CLIM command processor 
command and its arguments. 

clim:command-name cfekey : command-table 

The presentation type used to represent the name of a CLIM command 
processor command in the command table : command-table. 

clim:command-or-form &key : command-table 

The presentation type used to represent either a Lisp form or a CLIM 
command processor command and its arguments. 

The CLIM Command Processor 

This section describes the default behavior of the CLIM command processor. 

The command loop of a CLIM application is performed by the application's top- 
level function (see the section "Defining Application Frames in CLIM"). By default, 
this is clim:default-frame-top-level. After performing some initializations, 
clim:default-frame-top-level enters an infinite loop, reading and executing com- 
mands. It invokes the generic function clim:read-frame-command to read a com- 
mand which is then passed to the generic function clim:execute-frame-command 
for execution. The specialization of these generic functions is the simplest way to 
modify the command loop for your application. Other techniques would involve re- 
placing clim:default-frame-top-level with your own top level function. 

clim:read-frame-command invokes the command parser by establishing an input 
context of climrcommand. The input editor keeps track of the user's input, both 
from the keyboard and the pointer. Each of the command's arguments is parsed by 
establishing an input context of the arguments presentation type as described in 
the command's definition. Presentation translators provide the means by which the 
pointer can be used to enter command names and arguments using the pointer. 

climrread-command command-table &key (.stream *query-io*J (.-command-parser 
clim:*command-parser*J (xommand-unparser 

clim:*command-unparser*J Opartial-command-parser clim:*partial- 
command-parser*) .-use-keystrokes 
Reads a command. This function is not normally called by programmers. 

clim:read-frame-command frame &key .stream 

clim:read-frame-command reads a command from the user on the 
stream .stream, and returns the command object, frame is an application 
frame. You can specialize this generic function for your own application 
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frames, for example, if you want to have your application be able to read 
commands using keystroke accelerators. 

clim:execute-frame-command frame command 

clim:execute-frame-command executes the command command on behalf 
of the application frame frame. You can specialize this function if you 
want to change the behavior associated with the execution of commands. 

An application can control which commands are enabled and which are disabled on 
an individual basis. Use setf on climrcommand-enabled to control this mechanism. 
The user is not allowed to enter a disabled command via any interaction style. 

climrcommand-enabled command-name frame &optional command-table 

Returns t if the command named by command-name is presently enabled 
in command-table for the frame frame, otherwise returns nil. You can 
use setf on climrcommand-enabled in order to enable or disable a com- 
mand. 

The special variable climr*command-dispatchers* controls the behavior of the 
climrcommand-or-form presentation type. 

climr*command-dispatchers* 

This is a list of characters that indicate that CLIM should read a com- 
mand when CLIM is accepting input of type climrcommand-or-form. 



Menus and Dialogs in CLIM 



Concepts of Menus and Dialogs in CLIM 

CLIM provides three powerful menu interaction routines for allowing user interfac- 
ing through pop-up menus and dialogs, and menus and dialogs embedded in an ap- 
plication window: 

• climrmenu-choose is a straightforward menu generator that provides a quick 
way to construct menus. You can call it with a list of menu items. For a com- 
plete definition of menu item, see the function climrmenu-choose. 

• climrmenu-choose-from-drawer is a lower level routine that allows the user 
much more control in specifying the appearance and layout of a menu. You can 
call it with a window and a drawing function. Use this function for more ad- 
vanced, customized menus. 

• climraccepting-values provides the ability to build a dialog. You can specify sev- 
eral items that can be individually selected or modified within the dialog before 
dismissing it. It differs from the 'Select One' style of climrmenu-choose and 
climrmenu-choose-from-drawer. 
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Operators for Dealing with Menus and Dialogs in CLIM 

climrmenu-choose items &rest keys &key .-associated-window :text-style .-foreground 
.-background .-default-item .-label .scroll-bars .-printer .-presentation-type 
.-cache -.unique-id :id-test -.cache-value -.cache-test :max-width :max-height :n- 
rows :n-columns :x-spacing :y-spacing :row-wise :cell-align-x :cell-align-y :x- 
position :y-position .-pointer-documentation -.menu-type 

Displays a menu with the choices in item-list. It returns three values: 
the value of the chosen item, the item itself, and the gesture that select- 
ed it. If possible, CLIM will use the menu facilities provided by the host 
window system when you use climrmenu-choose. 

clim:menu-choose-from-drawer menu type drawer &key :x-position :y-position 
-.cache -.unique-id (:id-test #'equal) (-.cache-value t) (-.cache-test #'eql) :leave- 
menu-visible -.default-presentation 
The low-level routine used by CLIM for displaying menus. 

clim:draw-standard-menu menu presentation-type items default-item &key (-.item- 
printer #'clim:print-menu-itemj :max-width :max-height :n-rows :n- 
columns :x-spacing :y-spacing :row-wise (:cell-align-x 'rleftj (:cell-align-y 
'rtop) 

The function used by CLIM to draw the contents of a menu, unless the 
current frame manager determines that host window toolkit should be 
used to draw the menu instead. 

clim:print-menu-item menu-item &optional (stream *standard-output*J 
Given a menu item menu-item, display it on the stream stream. 

clim:with-menu (menu &optional associated-window &rest options &key -.label 
-.scroll-bars) &body body 

Binds menu to a temporary window, exposes the window on the same 
screen as the associated-window, runs the body, and de-exposes the win- 
dow. 

clim:*abort-menus-when-buried* 

Indicates whether or not CLIM should abort out of menus when they are 
"buried". 

climraccepting-values f&optional stream &key .-frame-class .-command-table .-own- 
window -.exit-boxes :align-prompts :initially-select-query-identifier imodify- 
initial-query :resynchronize-every-pass (-.check-overlapping t) .-label :x- 
position :y-position .-width .-height .scroll-bars -.text-style -.foreground -.back- 
ground) &body body 

A macro that builds a dialog for user interaction based on calls to 
climraccept within its body. 

climraccept-values-command-button (T&optional stream &key -.documentation 
-.query-identifier (-.cache-value t) (-.cache-test #'eql) -.view iresynchronize) 
prompt &body body) 

Displays prompt on stream and creates an area (the "button") which, 
when the pointer is clicked within it, causes body to be evaluated. This 
function can only be used within the climraccepting-values form. 
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Examples of Menus and Dialogs in CLIM 

Example of using clim:accepting-values 

This example sets up a dialog in the CLIM window stream that displays the cur- 
rent Month, Date, Hour and Minute (as obtained by a call to get-universal-time) 
and allows the user to modify those values. The user can select values to change 
by using the mouse to select values, typing in new values, and pressing RETURN. 
When done, the user selects "End" to accept the new values, or "Abort" to termi- 
nate without changes. 

(defun reset-clock (stream) 

(multiple-value-bind (second minute hour day month) 
(decode-universal-time (get-universal -time)) 
(declare (ignore second)) 
(format stream "Enter the time~%") 
(conditions: restart-case 
(progn 

(cl im:accepting-values (stream) 

(setq month (clim:accept 'integer :stream stream 

:default month :prompt "Month")) 
(terpri stream) 
(setq day (clim:accept 'integer :stream stream 

: default day : prompt "Day")) 
(terpri stream) 
(setq hour (clim:accept 'integer :stream stream 

:default hour :prompt "Hour")) 
(terpri stream) 
(setq minute (clim:accept 'integer :stream stream 

:default minute :prompt "Minute"))) 
;; This could be code to reset the time, but instead 
;; we're just printing it out 

(format t "~%New values: Month: ~D, Day: ~D, Time: ~D:~2,'0D." 
month day hour minute)) 
(abort () (format t "~&Time not set"))))) 

In CLIM, calls to climraccept do not automatically insert newlines. If you want to 
put each query on its own line of the dialog, use terpri between the calls to 
climraccept. 

Example of using clim:accept-values-command-button 

Here is the reset-clock example with the addition of a command button that will 
set the number of seconds to zero. 
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(defun reset-clock (stream) 

(multiple-value-bind (second minute hour day month) 
(decode-universal-time (get-universal -time)) 
(format stream "Enter the time~%") 
(conditions: restart-case 
(progn 

(cl im:accepting-values (stream) 

(setq month (clim:accept 'integer :stream stream 

:default month :prompt "Month")) 
(terpri stream) 
(setq day (clim:accept 'integer :stream stream 

: default day : prompt "Day")) 
(terpri stream) 
(setq hour (clim:accept 'integer :stream stream 

:default hour :prompt "Hour")) 
(terpri stream) 
(setq minute (clim:accept 'integer :stream stream 

:default minute :prompt "Minute")) 
(terpri stream) 

(cl im:accept-values-command-button (stream) "Zero seconds" 
(setq second 0))) 
;; this could be code to reset the time, but 
;; instead we're just printing it out 

(format t "~%New values: Month: ~D, Day: ~D, Time: ~D:~2, '0D:~2, '0D. 
month day hour minute second)) 
(abort () (format t "~&Time not set"))))) 

Using :resynchronize-every-pass in clim:accepting-values 

It often happens that the programmer wants to present a dialog where the individ- 
ual fields of the dialog depend on one another. For example, consider a spread- 
sheet with seven columns representing the days of a week. Each column is headed 
with that day's date. If the user inputs the date of any single day, the other dates 
can be computed from that single piece of input. 

If you build CLIM dialogs using climraccepting-values you can achieve this effect 
by using the :resynchronize-every-pass argument to climraccepting-values in 
conjunction with the rdefault argument to climraccept. There are three points to 
remember: 

• The entire body of the climraccepting-values runs each time the user modifies 
any field. The body can be made to run an extra time by specifying 
rresynchronize-every-pass t. Code in the body may be used to enforce con- 
straints among values. 

• If the rdefault argument to climraccept is used, then every time that call to 
climraccept is run, it will pick up the new value of the default. 

• Inside climraccepting-values, climraccept returns a third value, a boolean that 
indicates whether the returned value is the result of new input by the user, or 
is just the previously supplied default. 



Page 1388 



In this example we show a dialog that accepts two real numbers, delimiting an in- 
terval on the real line. The two values are labelled "Min" and "Max", but we 
wish to allow the user to supply a "Min" that is greater than the "Max", and au- 
tomatically exchange the values rather than signalling an error. 

(defun accepting-interval (&key (min -1.0) (max 1.0) (stream xquery-iox)) 
(cl im:accepting-values (stream : resynchronize-every-pass t) 
(fresh-line stream) 
(setq min (cl im: accept 'real :default min :prompt "Min" 

: stream stream)) 
(fresh-line stream) 
(setq max (clim:accept 'real :default max :prompt "Max" 

: stream stream)) 
(when (< max min) (rotatef min max))) 
(values min max)) 

(You may want to try this example after dropping the :resynchronize-every-pass 
and see the behavior. Without :resynchronize-every-pass, the constraint is still 
enforced, but the display lags behind the values and doesn't reflect the updated 
values immediately.) 

Use of the third value from clim:accept in clim:accepting-values 

As a second example, consider a dialog that accepts four real numbers that delimit 
a rectangular region in the plane, only we wish to enforce a constraint that the re- 
gion be a square. We allow the user to input any of "Xmin", "Xmax", "Ymin" or 
"Ymax", but enforce the constraint that 

Xmax - Xmin = Ymax - Ymin 

This constraint is a little harder to enforce. Presumably a user would be very dis- 
turbed if a value that he or she had just input was changed. So for this example 
we follow a policy that says if the user changed an X value, then only change Y 
values to enforce the constraint, and vice versa. When changing values we pre- 
serve the center of the interval. (This policy is somewhat arbitrary and only for 
the purposes of this example.) We use the third returned value from climraccept 
to control the constraint enforcement. 
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(defun accepting-square (&key (xmin -1.0) (xmax 1.0) (ymin -1.0) (ymax 1.0) 

(stream xquery-iox)) 
(let (xmin-changed xmax-changed ymin-changed ymax-changed ptype) 
(cl im:accepting-values (stream : resynchronize-every-pass t) 
(fresh-line stream) 

(mul tiple-value-setq (xmin ptype xmin-changed) 
(cl im: accept 'real :default xmin :prompt "Xmin" 
: stream stream)) 
(fresh-line stream) 

(mul tiple-value-setq (xmax ptype xmax-changed) 
(clim:accept 'real :default xmax :prompt "Xmax" 
: stream stream)) 
(fresh-line stream) 

(mul tiple-value-setq (ymin ptype ymin-changed) 
(clim:accept 'real :default ymin :prompt "Ymin" 
: stream stream)) 
(fresh-line stream) 

(mul tiple-value-setq (ymax ptype ymax-changed) 
(clim:accept 'real :default ymax :prompt "Ymax" 
: stream stream)) 
(cond ((or xmin-changed xmax-changed) 

(let ((y-center (/ (+ ymax ymin) 2.0)) 

(x-hal f-width (/ (- xmax xmin) 2.0))) 
(setq ymin (- y-center x-hal f-width) 

ymax (+ y-center x-hal f-width))) 
(setq xmin-changed nil xmax-changed nil)) 
((or ymin-changed ymax-changed) 
(let ((x-center (/ (+ xmax xmin) 2.0)) 

(y-hal f-width (/ (- ymax ymin) 2.0))) 
(setq xmin (- x-center y-hal f-width) 

xmax (+ x-center y-hal f-width))) 
(setq ymin-changed nil ymax-changed nil))))) 
(values xmin xmax ymin ymax)) 



Example of a dialog that uses gadgets 

Try the following example to see a dialog with gadgets in it. 
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(defun gadget-dialog-test (&optional (stream xstandard-inputx)) 
(let ((dest :file) 
(name "") 
(copies 0) 
(strip nil )) 
(cl im:accepting-values (stream :al ign-prompts t) 

(setq dest (clim:accept '(member :file :printer :window) 
:default dest :prompt "Destination type" 
:stream stream :view cl im:+gadget-dialog-view+)) 
(setq name (clim:accept 'string 

:default name :prompt "Destination name" 
:stream stream :view cl im:+text-f ield-view+)) 
(setq copies (clim:accept 'integer 

:default copies :prompt "Number of copies" 
:stream stream :view cl im:+sl ider-view+)) 
(setq strip (clim:accept 'boolean 

:default strip :prompt "Strip text styles" 
:stream stream :view cl im:+gadget-dialog-view+))) 
(values dest name strip))) 

Examples of using clim:menu-choose 

These examples show how to use climrmenu-choose. 

The simplest use of climrmenu-choose. If each item is not a list, the entire item 
will be printed and the entire item is the value to be returned too. 

(cl im:menu-choose '("One" "Two" "Seventeen")) 

If you want to return a value that is different from what was printed, the simplest 
method is as below. Each item is a list; the first element is what will be printed, 
the remainder of the list is treated as a plist — the rvalue property will be re- 
turned. (Note that nil is returned if you click on "Seventeen" since it has no 
rvalue.) 

(cl im:menu-choose '(("One" :value 1 : documentation "the loneliest number") 
("Two" :value 2 : documentation "for tea") 
("Seventeen" : documentation "what can be said about this?"))) 

The list of items you pass to climrmenu-choose might also serve some other pur- 
pose in your application. In that case, it might not be appropriate to put the print- 
ed appearance in the first element. You can supply a rprinter function which will 
be called on the item to produce its printed appearance. 

(cl im:menu-choose '(1 2 17) 

:printer ft' (lambda (item stream) 

(format stream "~R" item))) 



The items in the menu needn't be printed textually: 



Page 1391 



(cl im: menu-choose '(circle square triangle) 
:printer #' (lambda (item stream) 
(case item 

(circle (cl im:draw-ci rclex stream 10)) 
(square (cl im:draw-polygonx 

stream '(-8-8-88888 -8))) 
(triangle (cl im:draw-polygonx 

stream '(10 8 -10 -10 8)))))) 

The ritems option of the list form of menu item can be used to describe a set of 
hierarchical menus. 

(cl im:menu-choose 

'(("Class: Osteichthyes" 

: documentation "Bony fishes" 
:style (nil :italic nil)) 
("Class: Chondrichthyes" 
documentation "Cartilagenous fishes" 
:style (nil : ital ic nil ) 

: items (("Order: Squal iformes" documentation "Sharks") 
("Order: Rajiformes" documentation "Rays"))) 
("Class: Mammalia" 
documentation "Mammals" 
:style (nil : ital ic nil ) 
: items (("Order Rodentia" 

:items ("Family Sciuridae" 
"Family Muridae" 
"Family Cricetidae" 
("..." : value nil ))) 
("Order Carnivora" 
: items ("Family: Felidae" 
"Family: Canidae" 
"Family: Ursidae" 
("..." : value nil ))) 
("..." : value nil ))) 
("..." : value nil ))) 

Examples of using clim:menu-choose-from-drawer 

This example displays in the window *page-window* the choices "One" through 
"Ten" in bold type face. When the user selects one, the string is returned along 
with the gesture that selected it. 
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(cl im:menu-choose-f rom-drawer xpage-windowx 'string 
#' (lambda (stream type) 

(cl im:with-text-face (:stream bold) 
(dotimes (count 10) 
(cl im:present 

(string-capital ize 

(format nil "~R" (1+ count))) 
type : stream stream) 
(terpri stream))))) 

This example shows how you can use clim:menu-choose-from-drawer with 
clim:with-menu to create a temporary menu: 

(defun choose-compass-di recti on () 

(labels ((draw-compass-point (stream ptype symbol x y) 

(cl im:with-output-as-presentation (stream symbol ptype) 
(cl im:draw-stringx stream (symbol-name symbol) 

x y 

:align-x :center 
:align-y :center 
: text-style 

' ( : sans-serif : roman : large)))) 
(draw-compass (stream ptype) 

(cl im:draw-l ine* stream 25 -25 
: 1 ine-thickness 2) 
(cl im:draw-l ine* stream 25 -25 
: 1 ine-thickness 2) 
(loop for point in '((n -30) (s 30) 

(e 30 0) (w -30 0)) 
do (apply #'draw-compass-point 
stream ptype point)))) 
(cl im:with-menu (menu) 

(cl im : menu-choose- f rom-drawer 
menu 'cl im:menu-item tf'draw-compass)))) 



Output Recording in CLIM 



Concepts of CLIM Output Recording 

Output recording is a fundamental part of CLIM. It provides the basis for scrolling 
windows, for formatted output of tables and graphs, for the ability of presentations 
to retain their semantics, and for incremental redisplay. 

The output recording mechanism is enabled by default. Unless you turn it off, all 
output that occurs on a stream is captured and saved by the output recording 
mechanism. The output is captured in output records. The top-level output record, 
which contains all the output done on that stream, is called the history of the 
stream. 
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An output record is: 

• an object that contains more output records, or 

• a displayed output record (that is, a record that corresponds directly to 
something drawn on the display device). 

Since output records can contain other output records, we can view the organiza- 
tion of output records as a tree structure: 

History 




Each rectangle is an output record. The top-level record is an output record called 
a history. Each output record that is a leaf of the tree is called a displayed output 
record. The intermediate output records are both output records and children of 
their immediate superior. 

CLIM automatically segments the output into output records. The result of each 
atomic drawing operation is put into a new output record. Each presentation is put 
into a new output record. (Strings are treated differently; CLIM concatenates 
strings into one output record until a newline is encountered, which begins a new 
output record.) 

One use of an output record is to replay it; to produce the output again. Scrolling 
is implemented by replaying the appropriate output records. When using the tech- 
niques of incremental redisplay, your code determines which portions of the display 
have changed, then the appropriate output records are updated to the new state, 
and the output records are replayed. 

CLIM's table and graph formatters use output records. For example, your code us- 
es clim:formatting-table, and formats output into rows and cells; this output is 
sent to a particular stream. Invisibly to you, CLIM temporarily binds this stream 
to an intermediate stream, and runs a constraint engine over the code to deter- 
mine the layout of the table. The result is a set of output records which contain 
the table, its rows, and its cells. Finally, CLIM replays these output records to 
your original stream. 

Presentations are a special case of output records that remember the object and 
the type of object associated with the output. 

The concept of the tree structure organization of output records is illustrated by 
the organization of output records of a formatted table. The table itself is stored 
in an output record; each row has its own output record; each cell has its own out- 
put record. 
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CLIM Operators for Output Recording 

The purpose of output recording is to capture the output done by an application 
onto a stream. The objects used to capture output are called output records and 
displayed output records. An output record is an object that stores other output 
records. Displayed output records are the leaf objects that correspond to something 
visible on a display device. The following classes and predicates correspond to the 
objects used in output recording. 

climroutput-record 

The protocol class that is used to indicate that an object is an output 
record, that is, a CLIM object that contains other output records. 

clim:output-record-p object 

Returns t if and only object is of type climroutput-record. 

climrdisplayed-output-record 

The protocol class that is used to indicate that an object is a displayed 
output record, that is, a CLIM object that represents a visible piece of 
output on an output device. 

clim:displayed-output-record-p object 

Returns t if and only object is of type climrdisplayed-output-record. 

The following functions and macros can be used to create and operate on CLIM 
output records. 

climrreplay record stream &optional region 

Replays the output record record on stream. 

climrreplay-output-record record stream &optional region x-offset y-offset 

Replays all of the output captured by the output record record on stream. 
If region is not nil, then record is replayed if and only if it overlaps re- 
gion. 

climrwith-output-recording-options (stream &key :draw .-record) &body body 

Used to disable output recording and/or drawing on the given stream, 
within the extent of body. 

clim:with-new-output-record (stream &optional record-type record &rest initargs) 
&body body 

Creates a new output record, installs it in the output history of the 
stream, and then evaluates the body. 
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clim:with-output-to-output-record (stream &optional record-type record &rest ini- 
targs) &body body 

This is similar to clim:with-new-output-record except that the new out- 
put record is not inserted into the output record hierarchy. 

climroutput-record-parent record 

Returns the output record that it the parent of record. If record has no 
parent, climroutput-record-parent will return nil. 

climroutput-record-children record 

Returns a sequence of output records that are the children of the output 
record record. If record has no children, this will return nil. 

climrerase-output-record record stream &optional (errorp t) 

Erases the display of the output record record from stream, and removes 
the record from stream's output history. 

climradd-output-record child record 

Adds the output record child to the output record record. 

climrdelete-output-record child record &optional errorp 

Removes the child output record child from the output record record. 

climrclear-output-record record 

Removes all of the child output records from the output record record. 

clim:recompute-extent-for-new-child record child 

CLIM calls this function whenever a new child is added to an output 
record. It updates the bounding rectangle of record to be large enough to 
completely contain the new child output record child. 

clim:recompute-extent-for-changed-child record child old-left old-top old-right old- 
bottom 

CLIM calls this function whenever the bounding rectangle of one of the 
children of a record has been changed. It updates the bounding rectangle 
of record to be large enough to completely contain the new bounding 
rectangle of the child output record child. 

climrtree-recompute-extent record 

You can use this function whenever the bounding rectangles of a number 
of children of a record have been changed, such as happens during table 
and graph formatting, climrtree-recompute-extent computes the bound- 
ing rectangle large enough to contain all of the children of record, ad- 
justs the bounding rectangle of record accordingly, and then calls 
clim:recompute-extent-for-changed-child on record. 

The following functions can be used to apply a function to all of the children of an 
output record. 

clim:map-over-output-records function record &optional (x-offset 0) (y-offset 0) 
&rest continuation-args 

Applies function to all of the child output records in the output record 
record. Normally, function is called with a single argument, an output 
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record. If continuation-args are supplied, they are passed to function as 
well. 

clim:map-over-output-records-containing-position function record x y &optional 
x-offset y -offset &rest continuation-args 

Applies function to all of the child output records in the output record 
record that overlap the point (x,y). Normally, function is called with a 
single argument, an output record. If continuation-args are supplied, they 
are passed to function as well. 

clim:map-over-output-records-overlapping-region function record region &optional 
x-offset y -offset &rest continuation-args 

Applies function to all of the child output records in the output record 
record that overlap the region region. Normally, function is called with a 
single argument, an output record. If continuation-args are supplied, they 
are passed to function as well. 

The following functions control pointer sensitivity and highlighting for output 
records. 

clim:output-record-refined-position-test record x y 

CLIM uses clim:output-record-refined-position-test to definitively deter- 
mine that the point (x,y) is contained within the output record record. 

climrhighlight-output-record record stream state 

CLIM calls this method in order to draw highlighting for the output 
record record on stream, state is either :highlight (meaning to draw the 
highlighting) or runhighlight (meaning to erase the highlighting). 

In the present implementation of CLIM, the coordinates of output records are 
maintained relative to the coordinates of the output record's parent. Therefore, you 
must maintain the correct offsets while recursively mapping over output records, 
as the following example shows. 
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(defun describe-record (record &optional region) 
(labels ((describe (record x-offset y-offset) 
(format t "~&~S: " record) 

(cl im:with-bounding-rectanglex (left top right bottom) record 
(incf left x-offset) 
(incf top y-offset) 
(incf right x-offset) 
(incf bottom y-offset) 

(format t "~& (~D,~D) : (~D,~D) " left top right bottom) 
(multiple-value-bind (xoff yoff) 

(cl im:output-record-position record) 
(cl im: map-over-output- records-over lapping- region 
record region ^'describe 
(- x-offset) (- y-offset) 
(+ x-offset xoff) (+ y-offset yoff)))))) 
(declare (dynamic-extent ^'describe)) 
(describe record 0))) 

The relevant functions for locating an output record are: 

climroutput-record-position record 

Returns the X and Y position of record as two real numbers. The posi- 
tion is relative to the output record's parent, where (0,0) is the upper- 
left corner of the parent output record. 

clim:output-record-set-position record x y 

Changes the position of the output record record to the new position x 
and y. 

clim:convert-from-relative-to-absolute-coordinates stream output-record 

Returns the X and Y offsets that map the parent-relative coordinates of 
an output record to "absolute" coordinates. 

clim:convert-from-absolute-to-relative-coordinates stream output-record 

Returns the X and Y offsets that map the "absolute" coordinates of an 
output record to parent-relative coordinates. 

climrtranslate-coordinates x-delta y-delta &body coordinate-pairs 

Translates each of the X and Y coordinate pairs in coordinate-pairs by 
x-delta and y-delta. 

The following functions can be used to operate on output recording streams. 

clim:output-recording-stream-p object 

Returns t if and only if object is an output recording stream. 

climrstream-output-history stream 

Returns the top level output record for the stream stream. 

climrstream-replay stream &optional region 

Replays all of the output records in stream's output history that overlap 
the region region. If region is nil, all of the output records are replayed. 
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clim:stream-drawing-p stream 

Returns t if and only if drawing is enabled on the output recording 
stream stream. You can use setf on this to enable or disable drawing on 
the stream, or you can use the :draw option to climrwith-output- 
recording-options. 

clim:stream-recording-p stream 

Returns t if and only if output recording is enabled on the output 
recording stream stream. You can use setf on this to enable or disable 
output recording on the stream, or you can use the rrecord option to 
climrwith-output-recording-options. 

clim:stream-add-output-record stream record 

Adds the new output record record to stream's current output record 
(that is, climrstream-current-output-record). 

climrstream-current-output-record stream 

The current "open" output record for the output recording stream 
stream, that is, the one to which clim:stream-add-output-record will add 
a new child record. 

climrcopy-textual-output-history window stream &optional region record 

Given a window window that supports output recording, this function 
finds all of the textual output records that overlap the region region (or 
all of the textual output records is region is not supplied), and outputs 
that text to stream. 



Bounding Rectangles in CLIM 



Concepts of Bounding Rectangles 

Every bounded region has a derived bounding rectangle, which is a rectangular re- 
gion whose sides are parallel to the coordinate axes. The bounding rectangle for a 
region is the smallest rectangle that contains every point in the region, and may 
contain additional points as well. Unbounded regions do not have a bounding rect- 
angle. 

The bounding rectangle for an output record may have a different size depending 
on the display device on which the output record is drawn. Consider the case of 
drawing text on different output devices; the font chosen for a particular text style 
may vary considerably in size from one device to another. 

Bounding rectangles can be used for a variety of purposes. For example, repainting 
of windows is driven from bounding rectangles. clim:formatting-table and 
clim:format-graph-from-root run their constraint engines on bounding rectangles. 
Bounding rectangles are also used internally by CLIM to achieve greater efficien- 
cy. For instance, hit detection is done by initially seeing if a point is inside the 
bounding rectangle. 
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For output records that establish a new coordinate system (for example, records 
created by clim:formatting-row or clim:formatting-cell), the bounding rectangle 
of that record plays an additional important role: it establishes the coordinate sys- 
tem to which all inferior output records refer. The origin of the coordinate system 
in which the inferior records reside is the top left corner of the superior's bound- 
ing rectangle. 



CLIM Operators for Bounding Rectangles 

climrwith-bounding-rectangle* (left top right bottom) region &body body 

Binds left, top, right, and bottom to the edges of the bounding rectangle 
of region, and then evaluates body in that context. 

climrbounding-rectangle* region 

Returns the bounding rectangle of region as four real numbers that spec- 
ify the left, top, right, and bottom edges of the bounding rectangle. 

climrbounding-rectangle region 

Returns a new bounding rectangle for region as a climrstandard- 
bounding-rectangle object. 

climrmake-bounding-rectangle xl yl x2 y2 

Makes an object of class climrbounding-rectangle whose edges are par- 
allel to the coordinate axes. One corner is at (left,top) and the opposite 
corner is at (right, bottom). 

climrstandard-bounding-rectangle 

The standard instantiable class for bounding rectangles in CLIM. 

climrbounding-rectangle-left region 

Returns the coordinate of the left edge of the bounding rectangle of re- 
gion. 

climrbounding-rectangle-top region 

Returns the coordinate of the top edge of the bounding rectangle of re- 
gion. 

climrbounding-rectangle-right region 

Returns the coordinate of the right edge of the bounding rectangle of re- 
gion. 

climrbounding-rectangle-bottom region 

Returns the coordinate of the bottom edge of the bounding rectangle of 
region. 

climrbounding-rectangle-min-x region 

Returns the coordinate of the left edge of the bounding rectangle of re- 
gion. 

climrbounding-rectangle-min-y region 

Returns the coordinate of the top edge of the bounding rectangle of re- 
gion. 
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clim:bounding-rectangle-max-x region 

Returns the coordinate of the right edge of the bounding rectangle of re- 
gion. 

clim:bounding-rectangle-max-y region 

Returns the coordinate of the bottom edge of the bounding rectangle of 
region. 

climrbounding-rectangle-position region 

Returns the position of the bounding rectangle of region as two values, 
the left and top coordinates of the bounding rectangle. 

clim:bounding-rectangle-set-position region x y 

Changes the position of the bounding rectangle of region to the new posi- 
tion x and y. 

clim:bounding-rectangle-width region 

Returns the width of the bounding rectangle of region. 

climrbounding-rectangle-height region 

Returns the height of the bounding rectangle of region. 

clim:bounding-rectangle-size region 

Returns the size (as two values, width and height) of the bounding rect- 
angle of region. 

For example, the size of a the output generated by body can be determined by call- 
ing clim:bounding-rectangle-size on the output record: 

(let ((record (cl im:with-output-to-output-record (s) body))) 
(multiple-value-bind (width height) 

(cl im: bounding- rectangle-size record) 
(format t "~&Width is ~D, height is ~D" width height))) 



Formatted Output in CLIM 
Formatting Tables in CLIM 

Concepts of CLIM Table Formatting 

CLIM makes it easy to construct tabular output. The usual way of making tables 
is by indicating what you want to put in the table and letting CLIM choose the 
placement of the row and column cells. CLIM also allows you to specify constraints 
on the placement of the table elements with some flexibility. 

In the CLIM model of formatting tables, each cell of the table is handled sepa- 
rately, as though it has its own drawing surface. You write code which is designed 
to put ink on a drawing plane. That ink might be text, graphics, or both. CLIM 
surrounds all the ink with a bounding box (or, more precisely, an axis-aligned 
rectangle). That bounding box is snipped out of the drawing plane and placed in a 
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cell of the table. CLIM's table formatter puts whitespace around the ink to make 
sure that all the cells have the proper size and alignment. 

You are responsible only for specifying the contents of the cell. CLIM's table for- 
matter is responsible for figuring out how to lay out the table so that all the cells 
fit together properly. The table formatter determines the width of each column 
based on the the widest cell within the column. Similarly, it determines the height 
of each row based on the the tallest cell within the row. 

All the cells in a row all have the same height. All the cells in a column have the 
same width. The contents of the cells can be of irregular shapes and sizes. You 
can control how CLIM should place the objects within the cell by aligning them 
both vertically (to the top, bottom, or center of the cell) and horizontally (to the 
left, right, or center of the cell). 

You can specify other constraints that affect the appearance of the table (such as, 
the spacing between rows or columns, or the width or length of the table). 

Formatting Item Lists in CLIM 

Where table formatting is a "two-dimensional" operation from the point of view of 
the application, item list formatting is inherently one-dimensional output that is 
presented two-dimensionally. The canonical example is a menu, where the pro- 
grammer specifies a list of items to be presented, where a single column or row of 
menu entries would be fine (if the list is small enough). In this case, formatting is 
done when viewport requirements make it desirable. 

These constraints affect the appearance of item lists: 

• The number of rows (allowing CLIM to choose the number of columns) 

• The number of columns (allowing CLIM to choose the number of rows) 

• The maximum height (or width) of the column (letting CLIM determine 
the number of rows and columns that satisfy that constraint) 



CLIM Operators for Table Formatting 

This section summarizes the CLIM operators. For more complete documentation of 
each operator, see the section "Dictionary of CLIM Operators". 

These are the general-purpose table formatting operators: 

clim:formatting-table f&optional stream &rest options &key :x-spacing .y-spacing 
■.record-type .-multiple-columns :multiple-columns-x-spacing :equalize-column- 
widths (:move-cursor t)) &body body 

Establishes a "table formatting" context on the stream. All output per- 
formed within the extent of this macro will be displayed in tabular form. 
This must be used in conjunction with clim:formatting-row or 
climrformatting-column, and clim:formatting-cell. 

clim:formatting-row f&optional stream &key :record-type) &body body 

Establishes a "row" context on the stream. All output performed on the 
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stream within the extent of this macro will become the contents of one 
row of a table. clim:formatting-row must be used within the extent of 
clim:formatting-table, and it must be used in conjunction with 
clim:formatting-cell. 

climrformatting-column f&optional stream &key :record-type) &body body 

Establishes a "column" context on the stream. All output performed on 
the stream within the extent of this macro will become the contents of 
one column of the table, climrformatting-column must be used within 
the extent of climrformatting-table, and it must be used in conjunction 
with clim:formatting-cell. 

clim:formatting-cell f&optional stream &rest options &key (:align-x 'rleftj (:align-y 
':top) :min-width :min-height :record-type &allow-other-keysJ &body body 
Establishes a "cell" context on the stream. All output performed on the 
stream within the extent of this macro will become the contents of one 
cell in a table. clim:formatting-cell must be used within the extent of 
clim:formatting-row, climrformatting-column, or clim:formatting-item- 
list. 

These are the one-dimensional table formatting operators: 

clim:formatting-item-list f&optional stream &key :record-type :x-spacing :y-spacing 
.■initial-spacing :n-columns :n-rows :max-width :max-height .stream-width 
.stream-height (:row-wise t) (:move-cursor t)) &body body 
Use this macro to format the output in a tabular form, when the exact 
ordering and placement of the cells is not important, climrformatting- 
item-list must be used with clim:formatting-cell. 

clim:format-items items &key (.stream *standard-output*J sprinter .-presentation- 
type :x-spacing :y-spacing -.initial-spacing :n-rows :n-columns :max-width 
:max-height (:row-wise t) -.record-type (:cell-align-x 'rleftj (:cell-align-y ':top) 

Provides tabular formatting of a list of items. Each item in items is for- 
matted as a separate cell within the table. 

clim:format-textual-list sequence printer &key (.stream *standard-output*J (sepa- 
rator ", ") : conjunction 
Outputs a sequence of items as a textual list. 

clim:format-items is similar to clim:formatting-item-list. Both operators do the 
same thing, except they accept their input differently: 

• clim:formatting-item-list accepts its input as a body that calls 
clim:formatting-cell for each item. 

• clim:format-items accepts its input as a list of items with a specification 
of how to print them. 

In CLIM, menus use the one-dimensional table formatting model. 



Page 1403 



Examples of CLIM Table Formatting 

Formatting a table from a list 

The examplel function formats a simple table whose contents come from a list, 
(defvar xalphabetx '(abcdefghi j kl mnopqrstuvwxyz)) 

(defun examplel (&optional (items xalphabetx) 
&key (stream xstandard-outputx) 

(n-columns 6) x-spacing y-spacing) 
(cl im: formatting-table (stream :x-spacing x-spacing 

:y-spacing y-spacing) 
(do () ((null items)) 

(cl im: formatting-row (stream) 
(do ((i (1+ i))) 

((or (null items) (= i n-columns))) 
(cl im: formatting-cel 1 (stream) 

(format stream "~A" (pop items)))))))) 

Evaluating (examplel xalphabetx : stream xmy-windowx) shows this table: 

R B C D E F 

G H I J K L 

M N P D R 

S T U U W K 

Y Z 

The table above shows the result of evaluating examplel form without providing 
the :x-spacing and :y-spacing keywords. The defaults for these keywords makes 
tables whose elements are characters look reasonable. 

You can easily vary the number of columns, and the spacing between rows or be- 
tween columns. In the following example, we provide keyword arguments that 
change the appearance of the table. 

Evaluating this form 

(examplel xalphabetx : stream xmy-windowx : n-columns 10 

:x-spacing 10 :y-spacing 10) 



shows this table: 



RBCDEFGHIJ 
KLMNOPQRST 
U U W K Y Z 



(Note that this example could also be done with clim:formatting-item-list or 
clim:format-items, as shown in example4 below.) 
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Formatting a table representing a calendar month 

The calendar-month function shows how you can format a table that represents a 
calendar month. The first row in the table acts as column headings representing 
the days of the week. The following rows are numbers representing the day of the 
month. 

This example shows how you can align the contents of a cell. The column headings 
(Sun, Mon, Tue, etc.) are centered within the cells. However, the dates themselves 
(1, 2, 3, ... 31) are aligned to the right edge of the cells. The resulting calendar 
looks good, because the dates are aligned in the natural way. 

(defvar xdays-of-the-weekx (vector "Sun" "Mon" "Tue" "Wed" "Thu" "Fri" "Sat")) 

(defvar *month-lengths* (vector 31 28 31 30 31 30 31 31 30 31 30 31)) 
(defun days-in-month (month year) 
(if (= month 2) 

(if (zerop (mod year 4)) 

(if (zerop (mod year 400)) 28 29) 
28) 
(svref xmonth-lengthsx (1- month)))) 

(defun display-calendar (month year &key (stream xstandard-outputx)) 
(let ((days-in-month (days-in-month month year))) 

(multiple-value-bind (nil nil nil nil nil nil start-day) 

(decode-universal-time (encode-universal-time 1 month year)) 
(setq start-day (mod (+ start-day 1) 7)) 

(cl im: formatting-table (stream :x-spacing " " :y-spacing 2) 
(cl im: formatting-row (stream) 
(dotimes (d 7) 

(cl im: formatting-cel 1 (stream :align-x :center) 
(cl im:with-text-face (stream : italic) 

(write-string (svref xdays-of-the-weekx (mod d 7)) stream))))) 
(do ((date 1) 

(first-week t nil)) 
((> date days-in-month)) 
(cl im: formatting-row (stream) 
(dotimes (d 7) 

(cl im: formatting-cel 1 (stream :align-x :right) 
(when (and (<= date days-in-month) 

(or (not first-week) (>= d start-day))) 
(format stream "~D" date) 
(incf date)))))))))) 
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Evaluating (calendar-month 5 90 : stream xmy-windowx) shows this table: 



Sun Mon Tue Wed Thu Fri Sat 







1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 


16 


17 


18 


19 


20 


21 


22 


23 


24 


25 


26 


27 


28 


29 


30 


31 







Formatting a table with regular graphic elements 

The example2 function shows how you can draw graphics within the cells of a ta- 
ble. Each cell contains a rectangle of the same dimensions. Notice that, even 
though the example passes the same coordinates to climrdraw-rectangle* for each 
cell, the resulting table consists of a number of non-overlapping rectangles. 

(defun example2 (&key (stream xstandard-outputx) x-spacing y-spacing) 
(cl im: formatting-table (stream :x-spacing x-spacing 

:y-spacing y-spacing) 
(dotimes (i 3) 

(cl im: formatting-row (stream) 
(dotimes (j 3) 

(cl im: formatting-cel 1 (stream) 

(cl im:draw-rectangle* stream 10 10 50 50))))))) 

Evaluating (example2 : stream xmy-windowx : y-spacing 5) shows this table: 




Formatting a table with irregular graphics in the cells 

The example3 function shows how you can format a table in which each cell con- 
tains graphics of different sizes. 
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(defun example3 (&optional (items xalphabetx) 
&key (stream xstandard-outputx) 

(n-columns 6) x-spacing y-spacing) 
(cl im: formatting-table (stream :x-spacing x-spacing 

:y-spacing y-spacing) 
(do () ((null items)) 

(cl im: formatting-row (stream) 
(do ((i (1+ i))) 

((or (null items) (= i n-columns))) 
(cl im: formatting-cel 1 (stream) 
(cl im:draw-polygonx stream 

(list (* 10 (1+ (random 3))) 
5 5 (* 10 (1+ (random 3)))) 
:filled nil) 
(pop items))))))) 

Evaluating (example3 xalphabetx : stream xmy-windowx) shows this table: 

^V V vv 

Formatting a table of a sequence of items: clim:formatting-item-list 

The example4 function shows how you can use clim:formatting-item-list to format 
a table of a sequence of items, when the exact arrangement of the items and the 
table is not important. Note that you must use clim:formatting-cell inside the 
body of clim:formatting-item-list to output each item. You do not use 
climrformatting-column or clim:formatting-row, because CLIM figures out the 
number of columns and rows automatically (or obeys a constraint given in a key- 
word argument). 

(defun example4 (&optional (items xalphabetx) 

&key (stream xstandard-outputx) n-columns n-rows 
x-spacing y-spacing max-width max-height) 
(cl im: formatting-item-1 ist 

(stream :x-spacing x-spacing :y-spacing y-spacing 
: n-columns n-columns : n-rows n-rows 
:max-width max-width :max-height max-height) 
(do () ((null items)) 

(cl im: formatting-cel 1 (stream) 

(format stream "~A" (pop items)))))) 
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Evaluating (example4 : stream xmy-windowx) shows this table: 

R B C D 

E F G H 

I J K L 

M N P 

D R S T 

U U W K 

Y Z 

You can easily add a constraint specifying the number of columns. 

Evaluating (example4 : stream xmy-windowx :n-columns 8) shows this table: 

FIBCDEFGH 
IJKLMNOP 
QRSTUUWK 

Y Z 



Formatting Graphs in CLIM 



Concepts of CLIM Graph Formatting 

When you need to format a graph, you specify the nodes to be in the graph, and 
the scheme for organizing them. CLIM's graph formatter does the layout automat- 
ically, obeying any constraints that you supply. 

You can format any directed, acyclic graph (DAG). "Directed" means that the arcs 
on the graph have a direction. "Acyclic" means that there are no loops (or cycles) 
in the graph. 

Here is an example of such a graph: 




To specify the elements and the organization of the graph, you provide to CLIM 
the following information: 

• The root node. 

• A "node printer", a function used to display each node. The function is 
passed the object associated with a node and the stream on which to do 
output. 

• An "inferior producer", a function which takes one node and returns its 
inferior nodes (the nodes to which it points). 

Based on that information, CLIM lays out the graph for you. You can specify a 
number of options that control the appearance of the graph. For example, you can 
specify whether you want the graph to grow vertically (downward) or horizontally 
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(to the right). Note that CLIM's algorithm does the best layout it can, but compli- 
cated graphs can be difficult to lay out in a readable way. 



Examples of CLIM Graph Formatting 

(defstruct node 
(name "") 
(children nil)) 

(defvar g1 (let* ((2a (make-node :name "2A")) 
(2b (make-node :name "2B")) 
(2c (make-node :name "2C")) 

(1a (make-node :name "1A" :children (list 2a 2b))) 
(1b (make-node :name "1B" :children (list 2b 2c)))) 
(make-node :name "0" :children (list 1a 1b)))) 

(defun test-graph (root-node &rest keys) 

(apply #'cl im: format-graph-f rom-root root-node 
#' (lambda (node s) 

(write-string (node-name node) s)) 
tt'node-children 
keys)) 

Evaluating (test-graph g1 : stream xmy-windowx) results in the following graph: 




As shown above, by default, the graph has a horizontal orientation and grows to- 
ward the right. We can supply the rorientation keyword to control this. Evaluating 
(test-graph g1 : stream xmy-windowx : orientation : vertical) results in the follow- 
ing graph: 




CLIM Operators for Graph Formatting 

The following two functions can be used to format a graph. 

clim:format-graph-from-roots root-objects object-printer inferior-producer &key 
(.stream *standard-output*J (.-orientation 'rhorizontalj xenter-nodes :cut- 
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off-depth :merge-duplicates :graph-type (:duplicate-key #'identityj (dupli- 
cate-test #'eql) :arc-drawer : arc-drawing-options : generation-separation 
iwithin-generation-separation imaximize-generations (.store-objects t) (-move- 
cursor t) 

Constructs and displays a directed, acyclic graph, root-objects is a se- 
quence of the root elements of the set, from which the graph can be de- 
rived, object-printer is the function used to display each node of the 
graph; it takes to arguments, the object to display and the stream, inferi- 
or-producer is the function that to generates the inferiors from a node 
object; it takes one argument, the node, and returns a list of inferior 
nodes. 

clim:format-graph-from-root root-object object-printer inferior-producer &key 
(stream *standard-output*J (-orientation 'rhorizontalj xenter-nodes .-cut- 
off-depth :merge-duplicates -.graph-type (:duplicate-key#'identity) 
(■duplicate-test #'eql) -.arc-drawer : arc-drawing-options generation- 
separation iwithin-generation-separation imaximize-generations (store- 
objects t) (-move-cursor t) 

Like clim:format-graph-from-roots, except that root-object is a single 
root object instead of a sequence of roots. 



Formatting Text in CLIM 

CLIM provides the following two forms for breaking up lengthy output into multi- 
ple lines and for indenting output. 

climrfilling-output f&optional stream &rest keys &key (-fill-width '(80 :character)J 

(■break-characters '(#\Space)J : after-line-break : after-line-break-initially) 
&body body 

Binds stream to a stream that inserts line breaks into the output written 
to it so that the output is no wider then .-fill-width. The filled output is 
then written on the stream that is the original value of stream. 
climrfilling-output does not split "words" across lines. 

climrindenting-output (stream indentation &key (-move-cursor t)) &body body 

Binds stream to a stream that inserts whitespace at the beginning of 
each line, and writes the indented output as the stream that is the origi- 
nal value of stream. 

For example, you might use the following to generate a filled, indented list of the 
first twenty-one counting numbers: 
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(let ((stream xstandard-outputx)) 

(write-1 ine "Here are the first twenty-one counting numbers:" stream) 
(cl im: indenting-output (stream '(2 :character)) 

(cl im: f il 1 ing-output (stream :fill-width '(60 :character)) 
(dotimes (i 19) 

(format stream "~R, " i)) 
(format stream "and ~R." 20)))) 



Bordered Output in CLIM 

CLIM provides a mechanism for surrounding arbitrary output with some kind of a 
border. To specify that a border should be generated, you surround some code that 
does output with clim:surrounding-output-with-border, an advisory macro that 
describes the type of border to be drawn. 

clim:surrounding-output-with-border f&optional stream &key (.shape rrectanglej 

(■.move-cursor t)) &body body 

Binds the local environment in such a way that the output of body will 

be surrounded by a border of the specified .shape. 

clim:define-border-type shape arglist &body body 

Defines a new kind of border named shape, arglist will typically be 
(stream record left top right bottom). 

For example, the following produces a piece of output surrounded by a rectangle. 

(defun bordered-triangle (stream) 

(cl im:surrounding-output-with-border (stream :shape : rectangle) 
(clim:draw-polygon* stream '(40 120 50 140 30 140)))) 

The following is the result of evaluating (bordered-triangle xmy-windowx): 



Incremental Redisplay in CLIM 

Many applications can benefit greatly by the ability to redisplay information on a 
window only when that information has changed. This feature, called incremental 
redisplay, can significantly improve the speed at which your application updates in- 
formation on the screen. Incremental redisplay is very useful for programs that 
display a window of changing information, where some portions of the window are 
static, and some are continually changing. Genera's PEEK application is an exam- 
ple; this window displays the status of processes and other changing system infor- 
mation. 

CLIM's output recording mechanism provides the foundation for incremental redis- 
play. As an application programmer, you need to understand the concepts of output 
recording before learning how to use the techniques of incremental redisplay. 
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Concepts of Incremental Redisplay in CLIM 

Incremental redisplay is a facility to allow you to change the output in an output 
history (and hence, on the screen or other output device). It allows you to redis- 
play pieces of the existing output differently, under your control. 

It is "incremental" in the sense that CLIM redisplays only the part of the output 
history visible in the viewport, and only the portions of the output history that 
have changed, and thus need to be redisplayed. 

The way to do redisplay is to call climrredisplay on an output record that was cre- 
ated by climrupdating-output. This tells CLIM to start computing that output 
record over from scratch. CLIM compares the results with the existing output and 
tries to do minimal redisplay. The climrupdating-output form allows you to assist 
CLIM by informing it that entire branches of the output history are known not to 
have changed, climrupdating-output also allows you to communicate the fact that 
a piece of the output record hierarchy has moved. 

climrredisplay is often quite easy to use, and is useful in cases where there might 
be large changes between two passes, or where you have little idea as to what the 
changes might be. However, climrredisplay can be inefficient when you compare it 
to the best redisplay algorithm that you can implement for any particular special 
case. For example, a graphical editor whose operations affect only a single object 
(or a small number of objects) in a drawing might be a poor candidate for 
climrupdating-output. Because such an editor knows exactly what must be redis- 
played after an operation, it is probably more efficient to do redisplay "by hand". 
It is often appropriate to use incremental redisplay in order to get your application 
running, and then implement your own display later if incremental redisplay 
proves to be too slow. 



CLIM Operators for Incremental Redisplay 

The following functions are used to create an output record that should be incre- 
mentally redisplayed, and then to redisplay that record. 

climrupdating-output (stream &rest args &key (:record-type "climrstandard- 
updating-output-record) :unique-id (:id-test '#'eql) .-cache-value (xache- 
test '#'eql) xopy-cache-value .-parent-cache : output-record .-fixed-position .-all- 
new &allow-other-keys) &body body 

Informs the incremental redisplay module of the characteristics of the 
output done by body to stream. Within climrupdating-output, you name 
a piece of output (with a unique id), and you state how to determine 
whether the output changes (with a cache value). 

climrredisplay record stream &key (.-check-overlapping t) 

Causes the output of record to be recomputed. CLIM redisplays the 
changes incrementally, that is, only redisplays those parts of the record 
that changed. 
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climrredisplay-output-record record stream &optional check-overlapping x y 
parent-x parent-y 

Causes the output of record to be recomputed. CLIM redisplays the 
changes incrementally, that is, only redisplays those parts of the record 
that changed. 



Using climrupdating-output 

The primary technique of incremental redisplay is to use climrupdating-output to 
inform CLIM what output has changed, and use climrredisplay to recompute and 
redisplay that output. 

The outermost call to climrupdating-output identifies a program fragment that 
produces incrementally redisplayable output. A nested call to climrupdating-output 
(that is, a call to climrupdating-output that occurs during the evaluation of the 
body of the outermost climrupdating-output and specifies the same stream) identi- 
fies an individually redisplayable piece of output, the program fragment that pro- 
duces that output, and the circumstances under which that output needs to be re- 
drawn. 

The outermost call to climrupdating-output evaluates its body, producing the ini- 
tial version of the output, and returns an updating output record that captures the 
body in a closure. Each nested call to climrupdating-output caches its runique-id 
and rcache-value arguments and the portion of the output produced by its body. 

climrredisplay takes an updating output record and evaluates the captured body of 
climrupdating-output over again. When a nested call to climrupdating-output is 
evaluated during redisplay, climrupdating-output decides whether the cached out- 
put records can be reused or the output needs to be redrawn. This is controlled by 
the rcache-value argument to climrupdating-output. If its value matches its pre- 
vious value, the body would produce output identical to the previous output and 
thus is unnecessary. In this case the cached output records are reused and 
climrupdating-output does not re-execute its body. If the rcache-value does not 
match, the output needs to be redrawn, so climrupdating-output evaluates its 
body and the new output drawn on the stream replaces the previous output. The 
rcache-value argument is only meaningful for nested calls to climrupdating- 
output. 

If the rincremental-redisplay pane option is used, CLIM supplies the outermost 
call to climrupdating-output, saves the updating output record, and calls 
climrredisplay. The function specified by the r display-function pane option per- 
forms only the nested calls to climrupdating-output. 

If you use incremental redisplay without using the rincremental-redisplay pane 
option, you must perform the outermost call to climrupdating-output, save the up- 
dating output record, and call climrredisplay yourself. 

In order to compare the cache to the output record, two pieces of information are 
necessary: 
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• An association between the output being done by the program and a par- 
ticular cache. This is supplied in the :unique-id option to climrupdating- 
output. 

• A means of determining whether this particular cache is valid. This is 
the :cache-value option to climrupdating-output. 

Normally, you would supply both options. The unique-id would be some data struc- 
ture associated with the corresponding part of output. The cache value would be 
something in that data structure that changes whenever the output changes. 

It is valid to give the :unique-id and not the :cache-value. This is done to identify 
a superior in the hierarchy. By this means, the inferiors essentially get a more 
complex :unique-id when they are matched for output. (In other words, it is like 
using a telephone area code.) The cache without a cache value is never valid. Its 
inferiors always have to be checked. 

It is also valid to give the :cache-value and not the :unique-id. In this case, 
unique ids are just assigned sequentially. So, if output associated with the same 
thing is done in the same order each time, it isn't necessary to invent new unique 
ids for each piece. This is especially true in the case of inferiors of a cache with a 
unique id and no cache value of its own. In this case, the superior marks the par- 
ticular data structure, whose components can change individually, and the inferiors 
are always in the same order and properly identified by their superior and the or- 
der in which they are output. 

A :unique-id need not be unique across the entire redisplay, only among the infe- 
riors of a given output cache; that is, among all possible (current and additional) 
uses you make of climrupdating-output that are dynamically (not lexically) within 
another. 

To make your incremental redisplay maximally efficient, you should attempt to 
give as many caches with rcache-value as possible. For instance, if you have a 
deeply nested tree, it is better to be able to know when whole branches have not 
changed than to have to recurse to every single leaf and check it. So, if you are 
maintaining a modification tick in the leaves, it is better to also maintain one in 
their superiors and propagate the modification up when things change. While the 
simpler approach works, it requires CLIM to do more work than is necessary. 



Example of Incremental Redisplay in CLIM 

The following function illustrates the standard use of incremental redisplay: 
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(defun test (stream) 

(let* ((list (list 12 3 4 5)) 
(record 

(cl im:updating-output (stream) 

(do* ((elements list (cdr elements)) 
(count (1+ count)) 

(element (first elements) (first elements))) 
((null elements)) 
(cl im:updating-output (stream :unique-id count 

: cache-value element) 
(format stream "Element ~D" element) 
(terpri stream)))))) 
(sleep 10) 

(setf (nth 2 list) 17) 
(cl im: redisplay record stream))) 

When test is run on a window, the initial display looks like: 

Element 1 
Element 2 
Element 3 
Element 4 
Element 5 

After the sleep has terminated, the display looks like: 

Element 1 
Element 2 
Element 17 
Element 4 
Element 5 

Incremental redisplay takes care of ensuring that only the third line gets erased 
and redisplayed. In the case where items moved around, incremental redisplay en- 
sures that the minimum amount of work is done in updating the display, thereby 
minimizing "flashiness" while providing a powerful user interface. For example, 
try substituting the following for the form after the sleep: 

(setf list (sort list #' (lambda (&rest args) 

(zerop (random 2))))) 

Here is a little "process status" program that shows how to use incremental redis- 
play with table formatting. Notice the use of climrupdating-output around each 
row of the table to "name" each process, and the use of climrupdating-output's 
:cache-value option in each cell in the rows to indicate when a field has changed. 
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(defun show-processes (&optional (stream xstandard-outputx)) 
(cl im:with-end-of-l ine-action (stream :allow) 
(cl im:with-end-of-page-action (stream :allow) 
(let ((record 

(macrolet ((cell (stream item) 

1 (cl im: formatting-cel 1 (, stream) 
(format , stream "~A" , item)))) 
(cl im:updating-output (stream) 
(cl im: formatting-table (stream) 

(cl im:updating-output (stream :unique-id 'headings 

: cache-value 'constant) 
(cl im:with-text-face (stream : italic) 
(cl im: formatting-row (stream) 
(cell stream "Process") 
(cell stream "State") 
(cell stream "Activity")))) 
(let ((list (copy-list (cl im-sys:al 1-processes)))) 
(dolist (p list) 

(let ((name (cl im-sys:process-name p)) 

(state (cl im-sys:process-whostate p)) 
(activity (cl im-sys:process-state p))) 
(cl im:updating-output (stream :unique-id p) 
(cl im: formatting-row (stream) 

(cl im:updating-output (stream :cache-value name) 

(cell stream name)) 
(cl im:updating-output (stream :cache-value state) 

(cell stream state)) 
(cl im:updating-output (stream :cache-value activity) 
(cell stream (string-capitalize activity))))))))))))) 
(loop 

(sleep 1) 

(cl im: redisplay record stream)))))) 

The following is an example of how to use incremental redisplay with graph for- 
matting. Notice that you do not need to worry about redisplay of the graph's 
edges; CLIM does this for you. 

(defun redi splay-graph (stream) 

(macrolet ((make-node (&key name children) 
'(list* ,name , children)) 
(node-name (node) 

1 (car , node)) 
(node-children (node) 
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name 


"3A' 


)) 


name 


"3B' 


)) 


name 


"2A' 


)) 


name 


"2B' 


)) 


name 


"2C 


)) 


name 


"1A' 




name 


"1B' 





1 (cdr , node))) 
(let* ((3a (make-node 
(3b (make-node 
(2a (make-node 
(2b (make-node 
(2c (make-node 

(1a (make-node :name "1A" :children (list 2a 2b))) 
(1b (make-node :name "1B" :children (list 2b 2c))) 
(root (make-node :name "0" :children (list 1a 1b))) 
(graph 

(cl im:updating-output (stream :unique-id root) 
(cl im : format-graph-f rom-root 
root 
#' (lambda (node s) 

(cl im:updating-output (s :cache-value node) 
(write-string (node-name node) s))) 
#'cdr ;really #'node-children 
: stream stream)))) 
(sleep 2) 

(setf (node-children 2a) (list 3a 3b)) 
(cl im: redisplay graph stream) 
(sleep 2) 

(setf (node-children 2a) nil) 
(cl im: redisplay graph stream)))) 



Streams and Windows in CLIM 

CLIM performs many of its input and output operations on objects called streams. 
A stream is a special kind of sheet that supports the stream protocols. These pro- 
tocols are partitioned into two layers: the basic stream protocol and the extended 
stream protocol. 

The basic stream protocol is character-based and compatible with existing Common 
Lisp programs. (Note that the basic stream protocol is not documented in this user 
guide). 

The standard Common Lisp stream functions work on CLIM streams in all CLIM 
platforms. 

You can use the extended stream protocol to include pointer events and syn- 
chronous window-manager communication. 



Extended Stream Input in CLIM 

CLIM defines an extended input stream protocol. This protocol extends the basic 
Common Lisp input stream model to allow manipulation of non-character user ges- 
tures, such as pointer button presses. It also provides the basis for CLIM's input 
editor. 



Page 1417 



Operators for Extended Stream Input 

clim:extended-input-stream-p object 

Returns t if the object is a CLIM extended input stream, otherwise it re- 
turns nil. 

climrread-gesture &key (.stream *standard-input*J .-timeout :peek-p :input-wait-test 
:input-wait-handler :pointer-button-press-handler 

Returns the next gesture available in the input stream. Note that 
climrread-gesture does not echo character input. 

clim:stream-input-wait stream &key .-timeout :input-wait-test 

Waits until .-timeout or :input-wait-test, if specified. Otherwise the func- 
tion waits until there is input in the stream. 

climrunread-gesture gesture &key (.stream *standard-input*J 

Places the specified gesture back into .stream's input buffer. The next 
climrread-gesture request will return the unread gesture. The gesture 
supplied must be the most recent gesture read from the stream. 



Manipulating the Pointer in CLIM 



Concepts of Manipulating the Pointer in CLIM 

A pointer is an input device that enables pointing at an area of the screen (for 
example, a mouse, or a a tablet). CLIM offers a set of operators that enable you to 
manipulate the pointer. 



Operators for Manipulating the Pointer in CLIM 

These functions are the higher-level functions for doing input via the pointer. 

climrtracking-pointer f&optional stream &key .-pointer .-multiple-window itransformp 
(-.context-type t) .-highlight) &body clauses 

Provides a general means for running code while following the position 
of a pointing device, and monitoring for other input events. Programmer- 
supplied code may be run upon occurrence of events such as motion of 
the pointer, clicking of a pointer button, or typing something on the 
keyboard. 

climrdrag-output-record stream output-record &key (-repaint t) .-multiple-window 
.-erase .-feedback (:finish-on-release t) 

Enters an interaction mode in which user moves the pointer, and output- 
record follows the pointer by being dragged on stream. 

climrdragging-output f&optional stream &key (-repaint t) .-multiple-window -.finish- 
on-release) &body body 

Evaluates body to produce the output, and then invokes climrdrag- 
output-record to drag that output on stream. 



Page 1418 



clim:pointer-place-rubber-band-line* &key :start-x :start-y (.stream *standard- 
input*) .-pointer .-multiple-window (:finish-on-release t) 
Prompts for a line via the pointing device specified by .-pointer. 
clim:pointer-place-rubber-band-line* returns four values, the start-x, 
start-y, end-x, and end-y of a line. 

clim:pointer-input-rectangle* &key deft stop .-right .-bottom (.stream *standard- 
input*) .-pointer .-multiple-window (:finish-on-release t) 
Prompts for a rectangular area via the pointing device specified by 
.-pointer. clim:pointer-input-rectangle* returns four values, the left, top, 
right, and bottom edges of a rectangle. 

The following are lower level functions for managing the pointer more directly. 

climrstream-pointer-position stream &key .-pointer 

This function returns the position (two coordinate values) of the pointer 
in the stream's drawing plane coordinate system. You can use 
clim:stream-set-pointer-position to set the pointer position. 

clim:stream-set-pointer-position stream x y &key -.pointer 

This function sets the position (two coordinate values) of the -.pointer in 
the stream's drawing plane coordinate system. 

climrport-pointer port 

Returns the pointer object corresponding to the primary pointing device 
for the port port. 

clim:port-modifier-state basic-port 

Returns the state of the modifier keys for the port port. 

clim:pointer-button-state pointer 

Returns the current button state for pointer. 

climrpointer-position pointer 

This function returns the position (as two coordinate values) of the 
pointer pointer in the coordinate system of the sheet that the pointer is 
currently over. 

clim:pointer-set-position pointer x y 

This function changes the position of the pointer pointer to be (x,y). 

climrpointer-native-position pointer 

This function returns the position (as two coordinate values) of the 
pointer pointer in the coordinate system of the port's graft (that is, its 
"root window"). 

clim:pointer-set-native-position pointer x y 

This function changes the position of the pointer pointer to be (x,y). 

clim:pointer-sheet pointer 

Returns the sheet over which the pointer pointer is currently positioned. 

climrpointer-cursor pointer 

Returns the current cursor type for pointer. You can use setf to change 
it. 
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The Structure of the CLIM Input Editor 

CLIM's input editor provides interactive parsing and prompting by interacting with 
the rest of CLIM's input facility via rescanning. Rescanning is the process of reset- 
ting the internal state of the input editor and rereading the user's already-buffered 
input. CLIM input editing streams encapsulate interactive streams, that is, most 
stream operations are handled by the encapsulated interactive stream, but some 
operations are handled directly by the input editing stream itself. 

An input editing stream has the following components: 

• The encapsulated interactive stream. 

• A buffer with a fill pointer, which will be referred to as FP. The buffer 
contains all of the user's input, and FP is the length of that input. 

• An insertion pointer, which will be referred to as IP. The insertion 
pointer is the point in the buffer at which the "editing cursor" is. 

• A scan pointer, which will be referred to as SP. The scan pointer is the 
point in the buffer from which CLIM will get the next input gesture ob- 
ject (via climrread-gesture). 

• A "rescan queued" flag indicating that the programmer (or the input ed- 
itor itself) requested that a rescan operation should take place before the 
next gesture is read from the user. 

• A "rescan in progress" flag that indicates that CLIM is rescanning the 
user's input, rather than reading freshly supplied gestures from the user. 

The overall description of how the input editor works, is that it reads either 
"real" gestures from the user (such as characters from the keyboard or pointer 
button events), or input editing commands. The input editing commands can modi- 
fy the state of the input buffer. When such modifications take place, it is neces- 
sary to rescan the input buffer, that is, the input editor resets the scan pointer SP 
to its original state and reparses the contents of the input editor buffer before 
reading any other gestures from the user. While this rescanning operation is tak- 
ing place, the "rescan in progress" flag is set to t. The input editor always en- 
sures that SP is no greater than FP. 

The remainder of this section describes the input editor in more detail. If you plan 
to write complex climraccept methods, you may need to understand the input edi- 
tor at this level of detail. Otherwise, you may skip the rest of this section. 

The overall control structure of the input editor is: 

(catch 'rescan ; thrown to when a rescan is invoked 

(reset-scan-pointer stream) ;sets STREAM-RESCANNING-P to T 
(loop 

(funcall continuation stream))) 

where stream is the input editing stream and continuation is the code supplied by 
the programmer, which typically contains calls to such functions as climraccept 
and climrread-token. When a rescan operation is invoked, it has the effect of 
throwing to the rescan tag in the example above. The loop is terminated when an 
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activation gesture is seen, and at that point the values produced by continuation 
are returned as values from the input editor. 

The most important point is that functions such as climraccept, 
climrread-gesture, and climrunread-gesture read (or restore) the next gesture ob- 
ject from the buffer at the position pointed to by the scan pointer SP. However, 
insertion and input editing commands take place at the position pointed to by IP. 
The purpose of the rescanning operation is to eventually ensure that all of the 
user's input (typed characters, pointer button presses, and so forth) have been read 
by CLIM. During input editing, CLIM displays an editing cursor to remind you of 
the position of IP. 

The overall structure of climrread-gesture on an input editing stream is: 

(progn 

(rescan-if-necessary stream) 
(loop 

If SP is less than FP 

Then get the next gesture from the input editor buffer at SP 
and increment SP 

Else read the next gesture from the encapsulated stream 
and insert it into the buffer at IP 
Set the "rescan in progress" flag to false 
Call STREAM-PROCESS-GESTURE on the gesture 
If it was a "real" gesture 

Then exit with the gesture as the result 

Else it was an input editing command (which has already been 
processed), so continue looping 
)) 

When a new gesture object is inserted into the input editor buffer, it is inserted at 
the insertion pointer IP. If IP is equal to FP, this is accomplished by doing a 
vector-push-extend-like operation on the input buffer and FP, and then increment- 
ing IP. If IP is less than FP, CLIM first makes room for the new gesture in the 
input buffer, then inserts the gesture at IP, and finally increments both IP and 
FP. 

When the user requests an input editor motion command, only the insertion point- 
er IP is affected. Motion commands do not need to request a rescan operation. 

When the user requests an input editor deletion command, the user input at IP is 
removed, and IP and FP are modified to reflect the new state of the input buffer. 
Deletion commands (and other commands that modify the input buffer) arrange for 
a rescan to occur when they are done modifying the buffer, either by calling 
climrqueue-rescan or climrimmediate-rescan. 

CLIM sometimes inserts special objects in the input editor buffer, such as "noise 
strings" and "accept results". A noise string is used to represent some sort of in- 
line prompt and is never seen as user input; climrinput-editor-format and 
clim:prompt-for-accept methods insert noise strings into the input buffer. An ac- 
cept result is an object in the input buffer that is used to represent some object 
that was inserted into the input buffer (typically via a pointer gesture) that has no 
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readable representation (in the Lisp sense); clim:presentation-replace-input may 
create accept results. Noise strings are skipped over by input editing commands, 
and accept results are treated as a single gesture. 

The following forms are the most useful high-level operators for doing input edit- 
ing in CLIM: 

clim:with-input-editing f&optional stream &key dnput-sensitizer .-initial-contents 
.■class) &body body 

Establishes a context in which the user can edit the input he or she 
types in on the stream stream, body is then evaluated in this context, 
and the values returned by body are returned as the values of climrwith- 
input-editing. 

clim:with-input-editor-typeout f&optional stream &key .-erase) &body body 

If, when you are inside of a call to clim:with-input-editing, you want to 
perform some sort of typeout, it should be done inside climrwith-input- 
editor-typeout. 

climrinput-editor-format input-editing-stream format-string &rest format-args 

This function is like format, except that it is intended to be called on 
input editing streams. It arranges to insert "noise strings" in the input 
editor's input buffer. 

The following functions are lower-level functions used in writing more sophisticat- 
ed climraccept methods: 

clim:replace-input stream new-input &key .start send .-rescan -.buffer-start 
Replaces stream's input buffer with the string new-input. 

clim:presentation-replace-input stream object type view &key irescan -.buffer-start 

Like clim:replace-input, except that the new input to insert into the in- 
put buffer is gotten by presenting the object object with the presentation 
type type and view view . 

climrstream-insertion-pointer input-editing-stream 

Returns an integer corresponding to the current input position of input- 
editing-stream, that is, the point in the buffer at which the next user in- 
put gesture will be inserted. 

clim:stream-scan-pointer input-editing-stream 

Returns the current scan pointer (an integer) for input-editing-stream, 
that is, the point in the buffer at which calls to climraccept have 
stopped parsing input. 

clim:stream-rescanning-p input-editing-stream 

Returns the state of the input editing stream's "rescan in progress" 
flag, which is t if input-editing-stream is performing a rescan operation, 
otherwise it is nil. Non-input editing streams always return nil. 

climrimmediate-rescan input-editing-stream 

Invokes a rescan operation immediately on input-editing-stream by 
"throwing" out to the beginning of the most recent invocation of 
climrwith-input-editing. 
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climrqueue-rescan input-editing-stream &optional rescan-type 

Indicates that a rescan operation on input-editing-stream should take 
place after the next non-input editing gesture is read. 

clim:rescan-if-necessary input-editing-stream &optional inhibit-activation 

Invokes a rescan operation on the input editing stream input-editing- 
stream if climrqueue-rescan was called on the same stream and no in- 
tervening rescan operation has taken place. Resets the state of the "res- 
can queued" flag to nil. 

clim:reset-scan-pointer input-editing-stream &optional sp 

Sets input-editing-stream's scan pointer to sp (which defaults to 0) and 
sets the state of clim:stream-rescanning-p to t. 

clim:erase-input-buffer input-editing-stream &optional start-position 

Erases the part of the display that corresponds to the input editor's buf- 
fer starting at the position start-position. 

clim:redraw-input-buffer input-editing-stream &optional start-position 

Displays the input editor's buffer starting at the position start-position on 
the interactive stream that is encapsulated by the input editing stream 
input-editing-stream. 



Extended Stream Output in CLIM 

In addition to the basic output stream protocol, CLIM defines an extended output 
stream protocol. This protocol extends the stream model to allow the manipulation 
of a text cursor. 



Manipulating the Cursor in CLIM 

This protocol extends the stream model to allow manipulation of the cursor. 

A CLIM stream has a text cursor position, which is the place on the drawing 
plane where the next piece of text output will be drawn. Common Lisp stream out- 
put operations place text at the cursor position and advance the cursor position 
past the text. Certain CLIM output operations, such as climrpresent and 
clim:formatting-table, do the same. The CLIM draw functions, on the other hand, 
pay no attention to the text cursor position. 

Common Lisp stream input operations that echo, such as read-line, as well as 
climraccept, echo the input at the cursor position, and advance the cursor position. 

Operators for Manipulating the Cursor 

climrstream-cursor-position stream 

Returns two values, the X and Y coordinates of the cursor position on 
the drawing plane. 



Page 1423 



clim:stream-set-cursor-position stream x y 

Moves the cursor position to the specified X and Y coordinates on the 
drawing plane. 

climrstream-increment-cursor-position stream dx dy 

Moves the cursor position on stream relatively, adding dx to the X coor- 
dinate and adding dy to the Y coordinate. Either argument dx or dy can 
be nil, which means not to change that coordinate. 

climrcursor 

The protocol class that corresponds to a text cursor. 

climrcursor-position cursor 

Returns the cursor position of cursor as two values (X and Y), relative to 
the upper left corner of the sheet with which the cursor is associated. 

clim:cursor-set-position cursor x y 

Sets the cursor position of cursor to x and y, which are relative to the 
upper left corner of the sheet with which the cursor is associated. 

climrcursor-visibility cursor 

A convenience function that combines the functionality of both 
climrcursor-active and clim:cursor-state. 

clim:cursor-sheet cursor 

Returns the sheet with which cursor is associated. 



Text Measurement Operations in CLIM 

These functions compute the change in the cursor position that would occur if 
some text were output (that is, without actually doing any output, and without 
changing the cursor position). 

Operators for Text Measurements 

clim:text-size medium string &key :text-style -.start send 

Computes how the cursor position would move if the specified string or 
character were output starting at cursor position (0,0). It does not take 
into account the value of clim:stream-text-margin when computing the 
size of the output. 

clim:stream-character-width stream character &optional text-style 

Returns the horizontal motion of the cursor position that would occur if 
this character were output in this text-style. It does not take into account 
the value of clim:stream-text-margin when computing the size of the 
output. 

clim:stream-string-width stream string &key .start send :text-style 

Computes how the cursor position would move horizontally if the speci- 
fied string were output starting at the left margin. It does not take into 
account the value of clim:stream-text-margin when computing the size 
of the output. 
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clim:stream-line-height stream &optional text-style 

Returns what the line height of a line containing text in that text-style 
would be. text-style defaults to (clim:medium-text-style stream). 

climrstream-vertical-spacing stream 

Returns the current inter-line spacing for the stream stream. 

climrstream-baseline stream 

Returns the current text baseline for the stream stream. 

clim:stream-text-margin stream 

The X coordinate at which text wraps around (see clim:stream-end-of- 
line-action). The default setting is the width of the viewport, which is 
the right-hand edge of the viewport when it is horizontally scrolled all 
the way to the left. 



Attracting the User's Attention in CLIM 

CLIM supports the following operators for attracting the user's attention: 

climrbeep &optional (stream *standard-output*J 

Attracts the user's attention, usually with an audible sound. 

clim:notify-user frame message &key .-associated-window .-title -.exit-boxes -.text-style 
-.foreground -.background :x-position :y-position 

Notifies the user of some event on behalf of the application frame frame, 
message is a message string. 



Window Stream Operations in CLIM 

It is sometimes useful to perform some window management operations directly on 
a window. 



Clearing and Refreshing the Drawing Plane in CLIM 

CLIM supports the following operators for clearing and refreshing the drawing 
plane: 

clim:window-clear window 

Clears the entire drawing plane of window, filling it with the back- 
ground design, and discards the windows output history. 

clim:window-erase-viewport window 

Clears the visible part of the drawing plane of window, filling it with 
the background design. 

climrwindow-refresh window 

Clears the visible part of the drawing plane of window, and then replays 
all of the output records in the visible part of the drawing plane. 
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The Viewport and Scrolling in CLIM 

A window viewport is the region of the drawing plane that is visible through the 
window. You can change the viewport by scrolling or by reshaping the window. 
The viewport does not change if the window is covered by another window (that is, 
the viewport is the region of the drawing plane that would be visible if the win- 
dow were stacked on top). 

A window stream has an end-of-line action and an end-of-page action, which con- 
trol what happens when the cursor position moves out of the viewport (climrwith- 
end-of-line-action and clim:with-end-of-page-action, respectively). 

Viewport and Scrolling Operators 

climrwindow-viewport-position window 

Returns two values, the X and Y coordinates of the top-left corner of the 
window's viewport. 

clim:window-set-viewport-position window x y 

Moves the top-left corner of the window's viewport. This is how you 
scroll a window. 

climmote-viewport-position-changed frame pane x y 

CLIM calls this function whenever a pane gets scrolled, whether it is 
scrolled programmatically (by clim:window-set-viewport-position, for 
example) or by a user gesture (such as clicking on a scroll bar). 

climrscroll-extent sheet x y 

Scrolls the pane sheet in its viewport so that the position (x,y) of the 
pane is at the upper-left corner of the viewport. 

climrwindow-viewport window 

If the pane window is part of a scroller pane, this returns the region of 
window's viewport. Otherwise it returns the region of window itself. 

climrpane-viewport pane 

If the pane pane is part of a scroller pane, this returns the viewport 
pane for pane. Otherwise it returns nil. 

climrpane-viewport-region pane 

If the pane pane is part of a scroller pane, this returns the region of 
pane's viewport. Otherwise it returns nil. 

clim:stream-end-of-line-action stream 

Controls what happens when the cursor position moves horizontally out 
of the viewport (beyond the text margin). You can use setf on this to 
change the end of line action. 

clim:stream-end-of -page-action stream 

Controls what happens when the cursor position moves vertically out of 
the viewport. You can use setf on this to change the end of page action. 

clim:with-end-of-line-action (stream action) &body body 

Temporarily changes the end of line action for the duration of evaluation 
of body. 
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clim:with-end-of-page-action (stream action) &body body 

Temporarily changes the end of page action for the duration of evalua- 
tion of body. 



Functions for Operating on Windows Directly 

You can use climropen-window-stream to give you a CLIM window without incor- 
porating it into a frame. First use clim:find-port to make a port to pass as the 
:port argument. After calling climropen-window-stream, call climrwindow-expose 

to make the resulting window stream visible. 

Operators for Creating Ports and Frame Managers 

clim:find-port &rest initargs &key (.server-path clim:*default-server-path*J &al- 
low-other-keys 

Creates a port, a special object that acts as the "root" or "parent" of all 
CLIM windows and application frames. In general, a port corresponds to 
a connection to a display server. For making color windows under Gen- 
era, use the rscreen keyword in the server path argument to climrfind- 
port and give it the argument colorrcolor-screen. 

climrport object 

Given a CLIM object object, climrport returns the port associated with 
object. 

clim:destroy-port port 

Destroys the connection to the display server represented by port. 

clim:map-over-ports function 

Applies function to all of the current ports. 

clim:restart-port port 

Restarts the event process that manages the port port. 

clim:find-frame-manager &rest options &key sport (server-path clim:*default- 
server-path*) &allow-other-keys 

Finds a frame manager that is on the port sport, or creates a new one if 
none exists. 

climrframe-manager object 

Given a CLIM object object, climrframe-manager returns the frame man- 
ager associated with object. 

Operators for CLIM Primitive Layer for Window Streams 

climropen-window-stream &key sport sframe-manager sleft stop sright sbottom swidth 
.■height .-foreground .-background stext-style (-.vertical-spacing 2) (send-of-line- 
action rallowj (send-of-page-action rallowj soutput-record (sdraw t) (-record 
t) (sinitial-cursor-visibility roffj stext-margin : default-text-mar gin .save- 
under sinput-buffer (scroll-bars rverticalj .-borders -.label 
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A convenient interface for creating a CLIM window outside of an appli- 
cation frame. 

climrwindow-parent window 

Returns the window that is the parent (superior) of window. 

climrwindow-children window 

Returns a list of all of the windows that are children (inferiors) of win- 
dow. 

clim:window-label window 

Returns the label (a string) associated with window, or nil if there is 
none. 

clim:with-input-focus (stream) &body body 

Temporarily gives the keyboard input focus to the given window (which 
is most often an interactor pane). By default, a frame will give the input 
focus to the clim:frame-query-io pane. 

clim:stream-set-input-focus stream 

Gives the input focus to stream, and returns as a value the stream or 
sheet that previously had the input focus. 

The following functions are most usefully applied to the top level window of a 
frame. For example, 

(cl im: frame- top- level -sheet cl im:*appl i cat ion- frame*) 

climrwindow-expose window 

Makes the window visible on the screen. 

clim:window-stack-on-bottom window 

Puts the window underneath all other windows that it overlaps. 

clim:window-stack-on-top window 

Puts the window on top of all other windows that it overlaps, so you can 
see all of it. 

climrwindow-visibility stream 

A predicate that returns true if the window is visible. 

The following operators can be applied to a window to determine its position and 
size. 

clim:window-inside-edges window 

Returns four values, the coordinates of the left, top, right, and bottom 
inside edges of the window window. 

clim:window-inside-left window 

Returns the coordinate of the left edge of the window window. 

clim:window-inside-top window 

Returns the coordinate of the top edge of the window window. 
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clim:window-inside-right window 

Returns the coordinate of the right edge of the window window. 

climrwindow-inside-bottom window 

Returns the coordinate of the bottom edge of the window window. 

clim:window-inside-size window 

Returns the inside width and height of window as two values. 

clim:window-inside-width window 

Returns the inside width of window. 

climrwindow-inside-height window 

Returns the inside height of window. 



Hardcopy Streams in CLIM 

CLIM supports hardcopy output through the macro clim:with-output-to-postscript- 
stream: 

clim:with-output-to-postscript-stream (stream-var file-stream &key :device-type 
(.■orientation rportrait) :multi-page : scale-to- fit .-header-comments (.-destina- 
tion rprinterJJ &body body 

Within body stream-var is bound to a stream that produces PostScript 
code. This stream is suitable as a stream or medium argument to any 
CLIM output utility. A PostScript program describing the output to the 
stream-var stream will be written to stream. 

clim:new-page stream 

When called on a PostScript output stream, this causes a PostScript 
"newpage" command to be included in the output at the point climrnew- 
page is called. 

Example 

This example writes a PostScript program which draws a square, a circle and a 
triangle to a file named ICONS-OF-HIGH-TECH.PS. 
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(defun print-icons-of-high-tech-to-f ile () 

(with-open-f ile (file-stream "icons-of-high-tech.ps" 

:di recti on :output) 
(cl im:with-output-to-postscript-stream (stream file-stream) 
(let* ((x1 150) (y 250) (size 100) 
(x2 (+ x1 size)) 
(radius (/ size 2)) 

(base-y (+ y (/ (x size (sqrt 3)) 2)))) 
(cl im:draw-rectanglex stream 

(- x1 size) (- y size) 

x1 y) 
(cl im:draw-ci rclex stream 

(+ x2 radius) (- y radius) 
radius) 
(cl im:draw-trianglex stream 

(+ x1 radius) y 

x1 base-y 

x2 base-y))))) 

This example uses multi-page mode to draw a graph (by writing a PostScript pro- 
gram to the file some-pathname) of the subclasses of the class climrbounding- 
rectangle. 

(with-open-f ile (file some-pathname : direction : output) 

(cl im:with-output-to-postscript-stream (stream file :multi-page t) 

(cl im: format-graph- from- root (clos: find-class 'cl im: bounding- rectangle) 
#' (lambda (object s) 

(write-string (string (clos:class-name object)) s)) 
ft' cl os : cl ass-di rect-supercl asses 
: stream stream))) 

You can then use standard system facilities to print the file, such as Genera's 
Hardcopy File or the Unix lpr command. 



CLIM's Windowing Substrate 



Introduction to CLIM's Windowing Substrate 

One of the basic tasks in building user interfaces is allocating screen regions for 
particular purposes and recursively subdividing these regions into subregions. 
CLIM's windowing layer defines an extensible framework for constructing, using, 
and managing such hierarchies. This framework allows uniform treatment of the 
following things: 

• Window objects like those in X Windows. 

• Lightweight gadgets typical of toolkit layers, such as Motif or OpenLook. 

• Structured graphics like output records and presentations. 
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From the perspective of most CLIM users, CLIM's windowing layer plays the role 
of a window system. However, CLIM actually uses the services of a window system 
platform to provide efficient windowing, input, and output facilities. 

The fundamental unit of windowing defined by CLIM is called a sheet. A sheet can 
participate in a windowing relationship in which one sheet (the parent) provides 
space to a number of other sheets (called children). Support for establishing and 
maintaining this kind of relationship is the essence of what window systems pro- 
vide. 

Programmers can manipulate unrooted hierarchies of sheets (those without a con- 
nection to any particular display server). However, a sheet hierarchy must be at- 
tached to a display server to make it visible. Ports and grafts provide the function- 
ality for managing this capability. 

A port is a connection to a display service that is responsible for managing host 
display server resources and for processing input events received from the host 
display server. 

A graft is a special kind of top-level sheet that represents a host window, typically 
a root window (that is, a screen-level window). A sheet is attached to a display by 
making it a descendant of a graft that represents the appropriate host window. 
The sheet will then appear to be a child of that host window. So, a sheet is put 
onto a particular screen by making it a child of an appropriate graft and enabling 
it. 



Basic Sheet Protocols 

A sheet is the basic abstraction for implementing windows in CLIM. All sheets 
have the following basic properties: 

A coordinate system 

Provides the ability to refer to locations in a sheet's abstract 
plane. 

A region Defines an area within a sheet's coordinate system that indi- 

cates the area of interest within the plane, that is, a clipping 
region for output and input. This typically corresponds to the 
visible region of the sheet on the display. 

A parent A sheet that is the parent in a windowing relationship in 

which this sheet is a child. 

Children An ordered set of sheets that are each a child in a windowing 

relationship in which this sheet is a parent. The ordering of 
the set corresponds to the stacking order of the sheets. Not all 
sheets have children. 

A transformation Determines how points in this sheet's coordinate system are 
mapped into points in its parent, if it has a parent. 

An enabled flag Indicates whether the sheet is currently actively participating 
in the windowing relationship with its parent and siblings. 
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An event handler A procedure invoked when the display server wishes to inform 
CLIM of external events. 

Output state A set of values used when CLIM causes graphical or textual 

output to appear on the display. This state is often represented 
by a medium. 

climrsheet 

The protocol class that corresponds to a sheet. 

climrsheetp object 

Returns t if and only if object is of type climrsheet, otherwise returns 
nil. 

Furthermore, a sheet can participate in a number of protocols. Every sheet must 
provide or inherit methods for the generic functions that make up these protocols, 
or delegate some other sheet to handle the methods for it. 

These protocols are: 

The windowing protocol 

Describes the relationships between the sheet and its parent 
and children (and, by extension, all of its ancestors and de- 
scendants). 

The input protocol Provides the event handler for a sheet. Depending on the kind 
of sheet, input events may be handled synchronously, asyn- 
chronously, or not at all. 

The output protocol Provides graphical and textual output, and manages descriptive 
output state such as color, transformation, and clipping. 

The repaint protocol 

Invoked by the event handler and by user programs to ensure 
that the output appearing on the display device appears as the 
program expects it to appear. 

The notification protocol 

Invoked by the event handler and user programs to ensure that 
CLIM's representation of window system information is equiva- 
lent to the display server's. 



Sheet Geometry Protocols 

Every sheet has a region and a coordinate system. A sheet's region refers to its 
position and extent on the display device, and is represented by some sort of a re- 
gion object, frequently a rectangle. A sheet's coordinate system is represented by a 
coordinate transformation that converts coordinates in its coordinate system to co- 
ordinates in its parent's coordinate system. 

The following functions can be used to read or change the sheet's region and 
transformation: 
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climrsheet-region sheet 

Returns a region object that represents the set of points to which sheet 
refers. 

climrsheet-device-region sheet 

Returns a region object that describes the region that sheet occupies on 
the display device. The coordinates are in the host's native window coor- 
dinate system. 

climrsheet-transformation sheet 

Returns a transformation that converts coordinates in sheet's coordinate 
system into coordinates in its parent's coordinate system. 

climrsheet-device-transformation sheet 

Returns a transformation that converts coordinates in sheet's coordinate 
system into native coordinates on the display device. 

clim:note-sheet-region-changed sheet 

This function is invoked whenever the region of sheet is changed. 

clim:note-sheet-transformation-changed sheet 

This function is invoked whenever the transformation of sheet is 
changed. 

The following functions are more convenient interfaces used to change the region 
or location of a sheet: 

clim:move-sheet sheet x y 

Moves sheet to the new position (x,y). x and y are in coordinates relative 
to sheet's parent. 

clim:resize-sheet sheet width height 

Changes the size of sheet to have width width and height height. 

clim:move-and-resize-sheet sheet x y width height 

Moves sheet to the new position (x,y), and simultaneously changes the 
size of the sheet to have width width and height height, x and y are in 
coordinates relative to sheet's parent. 

The following functions can be used to convert a position in the coordinate system 
of one sheet to the coordinate system of a parent or child sheet: 

clim:map-sheet-position-to-parent sheet x y 

Applies sheet's transformation to the point (x,y), returning the coordi- 
nates of that point in sheet's parent's coordinate system. 

clim:map-sheet-position-to-child sheet x y 

Applies the inverse of sheet's transformation to the point (x,y) (represent- 
ed in sheet's parent's coordinate system), returning the coordinates of 
that same point in sheet's coordinate system. 

The following functions can be used to map over the sheets that contain a given 
position or region: 
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clim:map-over-sheets-containing-position function sheet x y 

Applies function to all of the children of sheet containing the position 
(x,y). x and y are expressed in sheet's coordinate system. 

clim:map-over-sheets-overlapping-region function sheet region 

Applies function to all of the children of sheet overlapping the region re- 
gion, region is expressed in sheet's coordinate system. 



Sheet Relationship Protocols 

Sheets are arranged in a tree-shaped hierarchy. In general, a sheet has one parent 
(or no parent) and zero or more children. A sheet may have zero or more siblings 
(that is, other sheets that share the same parent). 

The following terms are used to describe the relationships between sheets: 

Adopted A sheet is said to be adopted if it has a parent. A sheet be- 

comes the parent of another sheet by adopting that sheet. 

Disowned A sheet is said to be disowned if it does not have a parent. A 

sheet ceases to be a child of another sheet by being disowned. 

Grafted A sheet is said to be grafted when it is part of a sheet hierar- 

chy whose highest ancestor is a graft. In this case, the sheet 
may be visible on a particular window server. 

Degrafted A sheet is said to be degrafted when it is part of a sheet hier- 

archy that cannot possibly be visible on a server, that is, the 
highest ancestor is not a graft. 

Enabled A sheet is said to be enabled when it is actively participating 

in the windowing relationship with its parent. If a sheet is en- 
abled and grafted, and all its ancestors are enabled (they are 
grafted by definition), then the sheet will be visible if it occu- 
pies a portion of the graft region that isn't clipped by its an- 
cestors or ancestor's siblings. 

Disabled The opposite of enabled. 

The following generic functions comprise the sheet protocol. 

climrsheet-parent sheet 

Returns the sheet that is the parent of sheet, or nil if sheet has no par- 
ent. 

climrsheet-children sheet 

Returns a list of all of the sheets that are children of sheet. 

clim:sheet-adopt-child sheet child 

Adds the child sheet child to the set of children of sheet, and makes the 
sheet the child's parent. If child already has a parent, CLIM will signal 
an error. 
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clim:sheet-disown-child sheet child &key (serrorp t) 

Removes the child sheet child from the set of children of sheet, and 
makes the parent of the child be nil. 

clim:sheet-enabled-p sheet 

Returns t if sheet is enabled by its parent, otherwise returns nil. 

clim:map-over-sheets function sheet 

Applies function to sheet, and then applies function to all of the descen- 
dants of sheet. 



Sheet Input Protocols 

CLIM's windowing substrate provides an input architecture and standard function- 
ality for notifying clients of input that is distributed to their sheets. Input includes 
such events as the pointer entering and exiting sheets, pointer motion, and pointer 
button and keyboard events. At this level, input is represented as event objects. 

In addition to handling input event, a sheet is also responsible for providing other 
input services, such as controlling the pointer's appearance, and polling for current 
pointer and keyboard state. 

Input events can be broadly categorized into pointer events and keyboard events. 
By default, pointer events are dispatched to the lowest sheet in the hierarchy 
whose region contains the location of the pointer. Keyboard events are dispatched 
to the port's keyboard input focus; the accessor clim:port-keyboard-input-focus 
contains the event client that receives the port's keyboard events. 

Event objects and their accessors include: 

clim:device-event 

The superclass of all other CLIM device events. 

clim:event-sheet event 

Returns the window on which event occurred. 

clim:event-modifier-state event 

Returns the state of the keyboard's shift keys when the event event oc- 
curred. 

clim:pointer-motion-event 

The class that corresponds to the user moving the pointer. 

clim:pointer-enter-event 

The class that corresponds to the user moving the pointer into a sheet 
from another sheet. 

clim:pointer-exit-event 

The class that corresponds to the user moving the pointer out of a sheet. 

clim:pointer-button-press-event 

The class that corresponds to the user pressing a button on the pointer. 
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clim:pointer-button-release-event 

The class that corresponds to the user releasing a button on the pointer. 

clim:pointer-event-x pointer-event 

Returns the X position of the pointer when the pointer-event occurred. 

clim:pointer-event-y pointer-event 

Returns the Y position of the pointer when the pointer-event occurred. 

clim:pointer-event-button pointer-button-event 

Returns the button number that was pressed when the pointer button 
event pointer-button-event occurred. The values this can take are 
clim:+pointer-left-button+, clim:+pointer-middle-button+, or 

clim:+pointer-right-button+. 

clim:key-press-event 

The class that corresponds to pressing a key on the keyboard. 

clim:key-release-event 

The class that corresponds to releasing a key on the keyboard. 

clim:keyboard-event-key-name keyboard-event 

Returns the name of the key that was pressed or released in order to 
generate the keyboard event. 

The following are the most useful functions in the sheet input protocol. These are 
what you need to be aware of if you are writing your own classes of gadgets. 

clim:handle-event sheet event 

Handles the event event on behalf of sheet. 

clim:queue-event sheet event 

Inserts the event event into the queue of events for sheet. 

clim:sheet-event-queue sheet 

Returns the object that acts as the event queue. 

For more information on gadgets, see the section "Using Gadgets in CLIM". 



Sheet Output Protocols 

The output protocol is concerned with the appearance of displayed output on the 
window associated with a sheet. The sheet output protocol is responsible for pro- 
viding a means of doing output to a sheet, and for delivering repaint requests to 
the sheet's client. 

Each sheet maintains some output state that describes how output is to be ren- 
dered on its window. Such information as the foreground and background ink, line 
thickness, and transformation to be used during drawing are provided by this 
state. This state may be stored in the medium associated with the sheet itself, or 
it could be derived from a parent, or may have some global default, depending on 
the sheet itself. 
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The following comprises the basic medium protocol. For more detail on this, see 
the section "The CLIM Drawing Environment". 

climrmedium 

The protocol class that corresponds to a medium. 

climrmediump object 

Returns t if and only if object is of type climrmedium, otherwise returns 
nil. 

climrmedium-foreground medium 

Returns the current foreground design of the medium. You can use setf 
on climrmedium-foreground to change the foreground design. 

climrmedium-background medium 

Returns the current background design of the medium. You can use setf 
on climrmedium-background to change the background design. 

climrmedium-ink medium 

Returns the current drawing ink of the medium. You can use setf on 
climrmedium-ink to change the current ink. 

climrmedium-transformation medium 

Returns the current transformation of the medium. You can use setf on 
climrmedium-transformation to change the current transformation. 

climrmedium-clipping-region medium 

Returns the current clipping region of the medium. You can use setf on 
climrmedium-clipping-region to change the clipping region. 

climrmedium-line-style medium 

Returns the current line style of the medium. You can use setf on 
climrmedium-line-style to change the line style. 

climrmedium-text-style medium 

Returns the current text style of the medium. You can use setf on 
climrmedium-text-style to change the current text style. 

Before a sheet may be used for output, it must be associated with a medium. Some 
sheets are permanently associated with mediums for output efficiency; for example, 
CLIM stream panes have a medium that is permanently allocated to the window. 

However, many kinds of sheets only perform output infrequently, and therefore do 
not need to be associated with a medium except when output is actually required. 
Sheets without a permanently associated medium can be more lightweight than 
they otherwise would be. For example, in a program that creates a sheet for the 
purpose of displaying a border for another sheet, the border sheet only needs to do 
output only when the window's shape is changed. 

To associate a sheet with a medium, use the macro climrwith-sheet-medium. Only 
sheets that support output may have a medium associated with them. 

climrsheet-medium sheet 

Returns the medium associated with sheet. 
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clim:with-sheet-medium (medium sheet) &body body 

Within the body, the variable medium is bound to sheet's medium. If the 
sheet does not have a medium permanently allocated, one will be allocat- 
ed, associated with the sheet for the duration of the body, and deallocat- 
ed as the when the body has been exited. 

clim:medium-sheet medium 

Returns the sheet with which the medium medium is associated. 

climrmedium-drawable medium 

Returns the host window system object (or "drawable") that is drawn on 
by the CLIM drawing functions when they are called on medium. 



Sheet Repainting Protocols 

CLIM's repainting protocol is the mechanism whereby a program keeps the display 
up to date, reflecting the results of both synchronous and asynchronous events. 
The repaint mechanism may be invoked by user programs each time through their 
top-level command loop. It may also be invoked directly or indirectly as a result of 
events received from the display server host. For example, if a window is on dis- 
play with another window overlapping it, and the second window is buried, a 
"damage notification" event may be sent by the server; CLIM would cause a re- 
paint to be executed for the newly-exposed region. 

The following are the most useful functions in the repainting protocol. These are 
what you need to be aware of if you are writing your own classes of gadgets. 

climrhandle-repaint sheet region 

Implements repainting for a given sheet class. 

climrqueue-repaint sheet repaint-event 

Inserts the repaint event repaint-event into sheet's event queue. 

clim:repaint-sheet sheet region 

Causes sheet and all of its descendants that overlap the region region to 
be repainted. 



Ports and Mirrored Sheets 

A sheet hierarchy must be attached to a display server so as to permit input and 
output. This is managed by the use of ports and grafts. 

A port is a connection to a display server. It is responsible for managing display 
output and server resources, and for handling incoming input events. Typically, the 
programmer will create a single port that will manage all of the windows on its 
associated display. 

A graft is a special sheet that is directly connected to a display server. A graft is 
the CLIM sheet that represents the root window of the display. CLIM manages 
grafts invisibly, so you do not need to worry about grafts except to be aware of 
their existence. 
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To display a sheet on a display, it must have a graft for an ancestor. In addition, 
the sheet and all of its ancestors must be enabled, including the graft. In general, 
a sheet becomes grafted when it (or one of its ancestors) is adopted by a graft. 

A mirrored sheet is a special class of sheet that is attached directly to a window on 
a display server. Grafts, for example, are always mirrored sheets. However, any 
sheet anywhere in a sheet hierarchy may be a mirrored sheet. A mirrored sheet 
will usually contain a reference to a window system object, called a mirror. For 
example, a mirrored sheet "attached" to a machine running Genera will have a 
Genera window system object stored in one of its slots. Allowing mirrored sheets 
at any point in the hierarchy enables the adaptive toolkit facilities; for example, in 
Motif, scroll bars, sliders, push buttons, and so on, are all mirrored. 

Since not all sheets in the hierarchy have mirrors, there is no direct correspon- 
dence between the sheet hierarchy and the mirror hierarchy. However, on those 
display servers that support hierarchical windows, the hierarchies must be parallel. 
If a mirrored sheet is an ancestor of another mirrored sheet, their corresponding 
mirrors must have a similar ancestor/descendant relationship. 

CLIM interacts with mirrors when it must display output or process events. On 
output, the mirrored sheet closest in ancestry to the sheet on which we wish to 
draw provides the mirror on which to draw. The mirror's drawing clipping region 
is set up to be the intersection of the user's clipping region and the sheet's region 
(both transformed to the appropriate coordinate system) for the duration of the 
output. On input, events are delivered from mirrors to the sheet hierarchy. The 
CLIM port must determine which sheet shall receive events based on information 
such as the location of the pointer. 

In both of these cases, we must have a coordinate transformation that converts co- 
ordinates in the mirror (so-called "native" coordinates) into coordinates in the 
sheet and vice-versa. 

The following readers are useful when dealing with mirrored sheets: 

climrsheet-mirror sheet 

Returns the host window that is used to display sheet. 

climrsheet-device-region sheet 

Returns a region object that describes the region that sheet occupies on 
the display device. The coordinates are in the host's native window coor- 
dinate system. 

climrsheet-device-transformation sheet 

Returns a transformation that converts coordinates in sheet's coordinate 
system into native coordinates on the display device. 

A port is described with a server path, which is a list whose first element is a 
keyword that selects the kind of port. The remainder of the server path is a list of 
alternating keywords and values whose interpretation is port type-specific. 

The following functions are useful in creating and dealing with ports. 
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clim:find-port &rest initargs &key (.server-path clim:*default-server-path*J &al- 
low-other-keys 

Creates a port, a special object that acts as the "root" or "parent" of all 
CLIM windows and application frames. In general, a port corresponds to 
a connection to a display server. For making color windows under Gen- 
era, use the rscreen keyword in the server path argument to climrfind- 
port and give it the argument colorrcolor-screen. 

climrport object 

Given a CLIM object object, climrport returns the port associated with 
object. 

clim:map-over-ports function 

Applies function to all of the current ports. 

clim:port-name port 

Returns the name of the port as a string. 

clim:port-type port 

Returns the type of the port, that is, the first element of the server path 
specification. 

clim:port-server-path port 

Returns the server path associated with the port. 

clim:restart-port port 

Restarts the event process that manages the port port. 

clim:destroy-port port 

Destroys the connection to the display server represented by port. 



The clim-sys Package 

CLIM provides a number of useful "system-like" facilities, including multi- 
processing, locks, and resources. The operators for these facilities are all in the 
clim-sys package. 



Resources in CLIM 

CLIM provides a facility called resources that provides for reusing objects. A re- 
source describes how to construct an object, how to initialize and deinitialize it, 
and how an object should be selected from the resource of objects based on a set 
of parameters. 

clim-sys:defresource name parameters &key .-constructor .-initializer ideinitializer 
-.matcher -.initial-copies 

Defines a resource named name, parameters is a lambda-list giving 
names and default values (for optional and keyword parameters) of pa- 
rameters to an object of this type. 
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clim-sys:using-resource (variable resource &rest parameters) &body body 

The forms in body are evaluated with variable bound to an object allocat- 
ed from the resource named name, using the parameters given by param- 
eters. 

clim-sys:allocate-resource name &rest parameters 

Allocates an object from the resource named name, using the parameters 
given by parameters. 

clim-sys:deallocate-resource name object &optional allocation-key 
Returns the object object to the resource named name. 

clim-sys:clear-resource resource 

Clears the resource named name, that is, removes all of the resourced 
objects from the resource. 

clim-sys:map-resource function resource 

Calls function once on each object in the resource named name. 



Multi-processing in CLIM 

Most Lisp implementations provide some form of multi-processing. CLIM provides 
a set of functions that implement a uniform interface to the multi-processing 
functionality. Using these functions provides a higher degree of portability for your 
CLIM applications that use multi-processing. 

Important note: CLIM currently does not guard against multiple processes doing 
I/O on sheets, streams, mediums, and so forth. If you have an application that has 
multiple processes doing I/O onto the same output device, you must manage these 
processes and any locking issues yourself.See the section "Locks in CLIM". 

clim-sys:*multiprocessing-p* 

The value of this variable is t if the current Lisp environment supports 
multi-processing, otherwise it is nil. 

clim-sys:make-process function &key :name 

Creates a process named name. The new process will evaluate the func- 
tion function. 

clim-sys:processp object 

Returns t if object is a process, otherwise returns nil. 

clim-sys:destroy-process process 

Terminates the process process. 

clim-sys:current-process 

Returns the currently running process, which will be a process object. 

clim-sys:all-processes 

Returns a sequence of all of the currently running processes. 

clim-sys:process-name process 

Returns the name of the process process. 
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clim-sys:process-wait wait-reason predicate 

Causes the current process to wait until predicate returns a non-nil val- 
ue, predicate is a function of no arguments, reason is a "reason" for 
waiting, usually a string. 

clim-sys:process-wait-with-timeout wait-reason timeout predicate 

Causes the current process to wait until either predicate returns a 
non-nil value or the number of seconds specified by timeout has elapsed. 
predicate is a function of no arguments, reason is a "reason" for waiting, 
usually a string. 

clim-sys:process-yield 

Allows other processes to run. On systems that do not support multi- 
processing, this does nothing. 

clim-sys:process-interrupt process function 

Interrupts the process process and causes it to evaluate the function 
function. 

clim-sys:disable-process process 

Disables the process process, that is, prevents it from becoming runnable 
until it is enabled again. 

clim-sys:enable-process process 

Allows the process process to become runnable again after it has been 
disabled. 

clim-sys:restart-process process 

Restarts the process process by "unwinding" it to its initial state, and 
reinvoking its top-level function. 

clim-sys:without-scheduling &body forms 

Evaluates body in a context that is guaranteed to be free from interrup- 
tion by other processes. 



Locks in CLIM 

A lock is a software construct used for synchronization of two processes. A lock 
protects some resource or data structure so that only one process at a time can 
use it. A lock is either held by some process, or is free. When a process tries to 
seize a lock, it waits until the lock is free, and then it becomes the process hold- 
ing the lock. When it is finished, it unlocks the lock, allowing some other process 
to seize it. 

CLIM provides a portable interface to the locking primitives provided by most Lisp 
platforms. Using this interface provides a higher degree of portability for your 
CLIM applications that use locks. 

clim-sys:make-lock &optional (lock-name "a CLIM lock'V 

Creates a lock whose name is name, name is a string. 
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clim-sys:with-lock-held (place &optional state) &body forms 

Evaluates body while holding the lock named by place. 

clim-sys:make-recursive-lock &optional (lock-name "a recursive CLIM lock'V 

Creates a recursive lock whose name is name. 

clim-sys:with-recursive-lock-held (place &optional state) &body forms 

Evaluates body while holding the recursive lock named by place. 



CLIM Dictionary 

Dictionary of CLIM Operators 

climrabort-gesture Condition 

CLIM signals an climrabort-gesture condition whenever it reads an abort gesture 
from the user. For example, on Genera climrread-gesture will signal this condition 
if the user presses the RBORT key. 

See the macro climrcatch-abort-gestures. 

climrabort-gesture-event abort-gesture Generic Function 

Returns the event object that caused the abort gesture condition, abort-gesture, to 
be signalled. The event will usually be a climrkey-press-event object. 

clim:*abort-gestures* Variable 

A list of gestures that cause CLIM to abort out of the current input. 

When clim:stream-read-gesture reads a character, it checks to see if it is one of 
gestures in clim:*abort-gestures*. If it is, CLIM signals a condition of type 
climrabort-gesture. 

clim:*abort-menus-when-buried* Variable 

Indicates whether or not CLIM should abort out of menus when they are "buried". 

When clim:*abort-menus-when-buried* is t, climrmenu-choose and climrmenu- 

choose-from-drawer return nil for all their values, if the menu is aborted by 
burying it. When nil, the menu will await reexposure to become active again. 

climraccelerator-gesture Condition 

CLIM signals an climraccelerator-gesture condition whenever it reads an accelera- 
tor gesture from the user. If you use climrread-command-using-keystrokes, CLIM 
will handle this condition transparently. 
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climr*accelerator-gestures* Variable 

A list of gestures that CLIM will treat as keystroke accelerators when reading 
commands. 

When clim:stream-read-gesture reads a character, it checks to see if it is one of 
gestures in climr*accelerator-gestures*. If it is, CLIM signals a condition of type 
climraccelerator-gesture. 



clim:accelerator-gesture-event accelerator-gesture Generic Function 

Returns the event object that caused the accelerator gesture condition, accelerator- 
gesture, to be signalled. The event will usually be a clim:key-press-event object. 



climraccelerator-gesture-numeric-argument accelerator-gesture Generic Function 

Returns the numeric argument associated with the accelerator gesture condition, 
accelerator-gesture. If the user did not supply a numeric argument explicitly, this 
will return 1. 



climraccept type &rest accept-args &key (.stream *standard-input*) (:view 
(clim:stream-default-view stream),) .-default (-.default-type type) (-.history type) :pro- 
vide-default (-.prompt t) (-prompt-mode 'rnormal) (-display-default prompt) .-query- 
identifier .-activation-gestures -.additional-activation-gestures -.delimiter-gestures :addi- 
tional-delimiter-gestures -.insert-default (:replace-input t) (:active-p t) Function 

Requests input of the type from the stream, climraccept returns two values (or 
three values when inside of a call to climraccepting-values), the object and its 
presentation type, climraccept works by prompting, then establishing an input con- 
text via climrwith-input-context, and then calling the climraccept presentation 
method for type and -.view. 

For more information on using climraccept, see the section "Using CLIM Presen- 
tation Types for Input". 

Note that climraccept does not insert newlines. If you want to put prompts on sep- 
arate lines, especially in dialogs, use terpri to separate the calls to climraccept. 

type A presentation type specifier, type may be an presentation type ab- 

breviation. See the section "How to Specify a CLIM Presentation 
Type". See the section "Predefined Presentation Types in CLIM". 



stream 



-.view 



Specifies the input stream, and defaults to *standard-input*. 

An object representing a view. The default is (climrstream-default- 
view stream). For most streams, the default view is the textual 
view, climr+textual-view+. For dialog streams (that is, within 
climraccepting-values), the view will typically be either 
climr+textual-dialog-view+ or climr+gadget-dialog-view+. 
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.■default Specifies the object to be used as the default value for this call to 
climraccept. If this keyword is not supplied and :provide-default is t, 
then the default is determined by taking the most recent item from 
the presentation type history specified by the .-history argument. If 
.■default is supplied and the input provided by the user is empty, 
then .-default and :default-type are returned as the two values from 
climraccept. 

■.default-type 

If -.default is supplied and the input provided by the user is empty, 
then -.default and -.default-type are returned as the two values from 
climraccept. This defaults to type. 

.-history Specifies which presentation type's history to use for the default 
value for .-default and for the input editor's yanking commands. The 
default is to use the history for type. If .-history is nil, no history is 
used. 

.-provide-default 

Specifies whether or not to provide a default value for this call to 
climraccept if rdefault is not supplied. 

.-prompt If .-prompt is t, the prompt is a description of the type. If .-prompt is 
nil, prompting is suppressed. If it is a string, the string is displayed 
as the prompt. The default is t, which produces "Enter a type:" in a 
top-level climraccept or "(type)" in a nested climraccept. 

.-prompt-mode 

Can be mormal, the default, or rraw, which suppresses putting a 
colon after the prompt in a top-level call to climraccept and sup- 
presses putting parentheses around the prompt in a nested call to 
climraccept. In general, you will only use .-prompt-mode in nested 
calls to climraccept within a climraccept method. 

.-display-default 

When t, displays the default as part of the prompt, if one was sup- 
plied. When nil, the default is not displayed, .-display-default de- 
faults to t if there was a prompt, otherwise it defaults to nil. In 
general, you will only use .-display-default in nested calls to 
climraccept within a climraccept method. 

.-query-identifier 

This option is used to supply a unique identifier for each call to 
climraccept inside climraccepting-values. Outside of a call to 
climraccepting-values, .-query-identifier has no effect. See the sec- 
tion "Menus and Dialogs in CLIM". 

.-activation-gestures 

A list of gestures that overrides the current activation gestures, 
which terminate input. See the section "Input Editing and Built-in 
Keystroke Commands in CLIM". 
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:additional-activation-gestures 

A list of gestures that add to the activation gestures without over- 
riding the current ones. See the section "Input Editing and Built-in 
Keystroke Commands in CLIM". 

.■delimiter-gestures 

A list of gestures that overrides the current delimiter gestures, 
which terminate an individual token but not the entire input sen- 
tence. You will generally only use this when you are writing a 
climraccept method that will read multiple fields. See the section 
"Input Editing and Built-in Keystroke Commands in CLIM". 

:additional-delimiter-gestures 

A list of gestures that add to the delimiter gestures without over- 
riding the current ones. See the section "Input Editing and Built-in 
Keystroke Commands in CLIM". 

■.insert-default 

When t, inserts the default determined by the values of -.default and 
sprovide-default into the input buffer. The default is nil. 

:replace-input 

When t (the default) and the call to climraccept was satisfied by 
clicking on something with the pointer, CLIM uses 
climrpresentation-replace-input to insert the input into the input 
buffer. 

:active-p When t (the default), the call to climraccept will be considered 
"active" for input. When nil, climraccept will simply return the 
values of .-default and .-default-type without actually asking the user 
for any input. You can use this option to have fields in an 
climraccepting-values dialog that are visible, but not active for in- 
put. 



climraccept type-key parameters options type stream view &key .-default .-default-type 
&allow-other-keys Clim Presentation Method 

This presentation method is responsible for "parsing" the representation of type 
for a particular view view on the stream stream. The climraccept method should 
return a single value, the object that was "parsed", or two values, the object and 
its type (a presentation type specifier). The method's caller takes care of establish- 
ing the input context, defaulting, prompting, and input editing. 

.-default and .-default-type are the same as they are for climraccept. 

The method must specify &key, but need only receive the keyword arguments that 
it is interested in. The remaining keyword arguments will be ignored automatically 
since the generic function specifies &allow-other-keys. 

The climraccept method can specialize on the view argument in order to define 
more than one input view for the data. In particular, the climraccept method spe- 
cializing on the class climrtextual-view must be defined if the programmer wants 
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to allow the type to be used via the keyboard. CLIM uses the view argument to 
generate gadget fields within climraccepting-values. 

climraccept presentation methods can also call climraccept recursively. Such 
methods should be careful to call climraccept with rprompt nil and rdisplay- 
default nil, unless nested prompting is really desired. 

For more information on defining presentation types, see the section "Defining a 
New Presentation Type in CLIM". CLIM offers a number of other functions that 
are useful within climraccept methods. See the section "Utilities for climraccept 
Presentation Methods". 



climraccept-from-string type string &key (:view climr+textual-view+) .-default (de- 
fault-type type) .-activation-gestures -.additional-activation-gestures -.delimiter-gestures 
■.additional-delimiter-gestures (.start 0) send Function 

Reads the printed representation of an object of type type from string. This func- 
tion is similar to climraccept, except that the input is taken from string, starting 
at .start, and ending at send, -.view, -.default, -.default-type, -.activation-gestures, -.addi- 
tional-activation-gestures, -.delimiter-gestures, and -.additional-delimiter-gestures are 
used as they are for climraccept. This function is analogous to read-from-string. 

climraccept-from-string returns three values: the object, its presentation type, and 
the index in string of the next character after the input. 

If -.default is supplied, then the values of -.default and -.default-type are returned 
when the input string is empty. 



climraccept-present-default type-key parameters options type stream view default 
default-supplied-p present-p query-identifier &key (-prompt t) (:active-p t) &allow- 
other-keys Clim Presentation Method 

This presentation method is called by climraccept, which (in effect) turns into 
climrpresent inside of climraccepting-values. The default method calls 
climrpresent or climrdescribe-presentation-type depending on whether default- 
supplied-p is t or nil. 

type, stream, view, default, query-identifier, .-prompt, and :active-p are as for 
climraccept. default-supplied-p will be t if and only if the rdefault argument was 
explicitly supplied to the call to climraccept. 



climraccept-values-command-button (T&optional stream &key .-documentation 
.-query-identifier (-.cache-value t) (-.cache-test #'eql) -.view iresynchronize) prompt &body 
body) Function 

Displays prompt on stream and creates an area (the "button") which, when the 
pointer is clicked within it, causes body to be evaluated. This function can only be 
used within the climraccepting-values form, stream defaults to *standard-input*. 
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prompt A constant string, a compile-time constant that evaluates to a 
string, or a form which is used to draw the contents of the "but- 
ton". 

.■documentation 

An object that will be used to produce pointer documentation for 
the command button. If the object is a string, the string itself will 
be used as the documentation. Otherwise, it must be a function of 
one argument, the stream to which the documentation will be writ- 
ten. The default is prompt. 

.■query-identifier 

A query identifier that uniquely identifies the command button. 
This option is the same as it is for climraccept within 
climraccepting-values. 

-.view A view object, used to select how the button will appear. Some 
frame managers will use a climrpush-button gadget for the com- 
mand button. 

■.cache-value 

A value that remains constant if the output produced by body does 
not need to be recomputed, -.cache-value is used by an internal call 
to climrupdating-output. 

■.cache-test A function of two arguments that is used for comparing cache val- 
ues, -.cache-test is used by an internal call to climrupdating-output. 

-.resynchronize 

When this is t, the dialog is redisplayed on additional time whenev- 
er the command button is clicked on. See the rresynchronize-every- 
pass argument to climraccepting-values for more information. 

See the section "Examples of Menus and Dialogs in CLIM". 



climraccept-values-command-parser command-name command-table stream partial- 
command &key -.own-window Function 

Reads the remaining arguments of a partially filled-in command on behalf of an 
application frame's command loop by getting input via a dialog. User programs 
should not call this function explicitly, but should rather bind climr*partial- 
command-parser* to it. 

climrcommand-line-read-remaining-arguments-for-partial-command uses this 
function when the unsupplied arguments are in the middle of the command line 
rather than at the very end of the command line. 



climraccept-values-pane Class 

The pane class that is used to implement modeless climraccepting-values dialog 
panes. It corresponds to the pane type abbreviation r accept- values in the rpanes 
clause of climrdefine-application-frame. 
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See the section "Using the rpanes Option to clim:define-application-frame" and 
see the section "Menus and Dialogs in CLIM". 



clim:accept-values-pane Clim Command Table 

When you use an climraccept-values pane as one of the panes in a climrdefine- 
application-frame, you must inherit from this command table in order to get the 
commands that operate on the dialog. 



clim:accept-values-pane-displayer frame pane &key :displayer :resynchronize-every- 
pass (icheck-overlapping t) :align-prompts :max-height :max-width Function 

When you use an : accept- values pane, the display function must use climraccept- 
values-pane-displayer. See the section "Using an : accept- values Pane in a CLIM 
Application Frame". 

-.displayer is a function that is the body of an climraccepting-values dialog. It 
takes two arguments, the frame and a stream. The display function should not call 
climraccepting-values itself, since that is done by climraccept-values-pane- 
displayer. 

The :resynchronize-every-pass, .-check-overlapping, and :align-prompts argument are 
the same as they are for climraccepting-values. 

:max-height and :max-width are used to constraint the maximum size of the dialog 
within the pane. They are typically used only when CLIM is composing layout of 
the entire application frame. 

See the section "Examples of CLIM Application Frames". 



climraccepting-values f&optional stream &key .-frame-class .-command-table .-own- 
window -.exit-boxes :align-prompts :initially-select-query-identifier :modify-initial-query 
:resynchronize-every-pass (-.check-overlapping t) .-label :x-position :y-position .-width 
.-height .scroll-bars .-text-style .-foreground .-background) &body body Macro 

Builds a dialog for user interaction based on calls to climraccept on the stream 
stream within its body. The user can select the values and change them, or use de- 
faults if they are supplied. The dialog will also contain 'Abort" and "End" choic- 
es. If the "End" choice is selected then climraccepting-values returns whatever 
values the body returns. If the "Abort" choice is selected, climraccepting-values 
will invoke the conditionsrabort restart. Callers of climraccepting-values may 
want to use conditionsrrestart-case or conditionsrwith-simple-restart in order to 
locally establish a conditionsrabort restart. 

stream The stream climraccepting-values will use to build up the dialog. 
When stream is t, that means *standard-input*. 

body The body of the macro, which contains calls to climraccept that 

will be intercepted by climraccepting-values and used to build up 
the dialog. 
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.-frame-class 

The type of dialog frame to create. The default is to use CLIM's 
"usual" dialog class (either climraccept-values or climraccept- 
values-own- window). This option allows you to specialize the 
climraccept-values class, and to customize some of the behavior of 
dialogs. 

:own-window 

When :own-window is t, the dialog will appear in its own "popped- 
up" window. In this case the initial value of stream is a window 
with which the dialog is associated. This is similar to the 
: associated- window argument to climrmenu-choose. Within the 
body, the value of stream will be the "popped-up" window. 

The value of :own-window can be nil, t, or a list of alternating key- 
word options and values. The accepted options are rright-margin 
and rbottom-margin; their values control the amount of extra space 
to the right of and below the dialog (useful if the user's responses 
to the dialog take up more space than the initially displayed de- 
faults). The allowed values for rright-margin are the same as for 
the :x-spacing option to climrformatting-table; the allowed values 
for rbottom-margin are the same as for the ry-spacing option to 
climrformatting-table. 

■.exit-boxes Allows you to specify what the exit boxes should look like. The de- 
fault behavior in Genera is as though you specified the following: 

'((:exit "<End> uses these values") 
(: abort "<Abort> aborts")) 

See the generic function climrdisplay-exit-boxes. 

:align-prompts 

When t, CLIM formats the dialogs so that all of the prompts are 
right-aligned in a vertical stack, and all of the input fields are left- 
aligned in a stack just to the right of the prompts. This can some- 
times make for more attractive dialogs. The default is nil. 

:initially-select-query-identifier 

Specifies that a particular field in the dialog should be pre-selected 
when the user interaction begins. The field to be selected is tagged 
by the r query-identifier option to climraccept; use this tag as the 
value for the :initially-select-query-identifier option, as shown in the 
following example: 
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(defun simple-dialog () 
(let (a b c) 

(cl im: accepting- values 

(xquery-iox : initial ly-select-query-identif ier 'the-tag) 
(setq a (cl im:accept 'pathname :prompt "A pathname")) 
(terpri xquery-iox) 
(setq b (clim:accept 'integer :prompt "A number" 

:query-identif ier 'the-tag)) 
(terpri xquery-iox) 

(setq c (clim:accept 'string :prompt "A string"))) 
(values a b c))) 

When the initial display is output, the input editor cursor appears 
after the prompt of the tagged field, just as if the user had selected 
that field by clicking on it. The default value, if any, for the select- 
ed field is not displayed. 

:modify-initial-query 

When :initially-select-query-identifier is supplied and :modify-initial- 
query is t, the initially selected field will be selected in a "modify" 
mode. That is, the input buffer will contain the default for the field, 
and the user can then edit it. 

:resynchronize-every-pass 

A boolean option specifying whether earlier queries depend on later 
values; the default is nil. 

When :resynchronize-every-pass is t, the contents of the dialog are 
redisplayed an additional time after each user interaction. This has 
the effect of ensuring that, when the value of some field of a dialog 
depends on the value of another field, all of the displayed fields will 
be up to date. 

You can use this option to dynamically alter the dialog. The follow- 
ing is a simple example. It initially displays an integer field that 
disappears if a value other than 1 is entered; in its place a two-field 
display appears. 

(defun al ter-mul tiple-accept () 
(let ((flag 1)) 

(cl im: accepting- values (xquery-iox 

: resynchronize-every-pass t) 
(setq flag (clim:accept 'integer 

:default flag :prompt "Number")) 
(when (= flag 1) 
(terpri xquery-iox) 

(clim:accept 'string :prompt "String") 
(terpri xquery-iox) 
(clim:accept 'pathname :prompt "Pathname"))))) 
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As the example shows, to use this option effectively, the controlling 
variable(s) must be initialized outside the lexical scope of the 
climraccepting-values macro. 

.-label Allows you to specify a label in :own-window t dialogs. This is just 
like the .-label option to climrmenu-choose. 

:x-position and :y-position 

Allow you to specify where an :own-window t dialog will come up. 
By default, the dialog will come up "near" the current position of 
the pointer. These are just like the options of the same name to 
climrmenu-choose. 

.-text-style The default text style to use for the dialog. 

.-foreground and .-background 

These specify the default foreground and background for rown- 
window t dialogs. These default from the associated window. 

.scroll-bars 

This can be nil, rnone, rhorizontal, rvertical, or rboth. This speci- 
fies whether or not there are scroll bars for :own-window t dialogs. 
The default is rvertical. 

Note: you must specify either a unique prompt or a query-identifier for each 
climraccept form within an climraccepting-values form; otherwise, there will be 
no way that the dialog can identify which climraccept form is being run. 

See the section "Examples of Menus and Dialogs in CLIM". 



climraction-gadget Class 

The class used by gadgets that perform some kind of action, such as a push but- 
ton; a subclass of climrbasic-gadget. 

All subclasses of climraction-gadget must handle the ractivate-callback initarg, 
which is used to specify the activate callback of the gadget. The activate callback 
is nil or a function of one argument, the gadget. 



climractivate-callback gadget client id Generic Function 

This callback is invoked when the gadget is activated. 

The default method (on climraction-gadget) calls the function specified by the 
ractivate-callback initarg with one argument, the gadget. 

See the section "Using Gadgets in CLIM". 

climractivate-gadget gadget Generic Function 

Causes the gadget to become active, that is, available for input. The function 
climrnote-gadget-activated is called whenever the gadget is made active. 
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clim:activation-gesture-p gesture Function 

Returns t if gesture is a currently active activation gesture. 

clim:*activation-gestures* Variable 

A list containing the gesture names of the currently active activation gestures. 



clim:add-command-to-command-table command-name command-table &key :name 
-.menu -.keystroke (:errorp t) Function 

Adds the command named by command-name to the command table command-table, 
command-table may be either a command table or a symbol that names a command 
table. The keyword arguments are: 

-.name The command-line name for the command, which can be nil, t, or a 
string. When it is nil, the command will not be available via com- 
mand-line interactions. When it is a string, that string is the com- 
mand-line name for the command. When it is t, the command-line 
name is generated automatically by calling clim:command-name- 
from-symbol. 

For the purposes of command-line name lookup, the character case 
of name is ignored. 

-.menu A command menu item for the command, which can be nil, t, a 
string, or a cons. When it is nil, the command will not be available 
via menus. When it is a string, the string will be used as the menu 
name. When it is t, an automatically generated menu name will be 
used. When it is a cons of the form {string . menu-options), then 
string is the menu name and menu-options consists of keyword-value 
pairs. The valid keywords are rafter and : documentation, which are 
interpreted as for clim:add-menu-item-to-command-table. 

keystroke The value for keystroke is either a standard character, a gesture 
spec, or nil. When it is a character or gesture spec, it is the 
keystroke accelerator for the command; otherwise the command will 
not be available via keystroke accelerators. 

:errorp If the command is already present in the command table and :errorp 
is t, the climrcommand-already-present condition will be signalled. 
When the command is already present in the command table and 
:errorp is nil, then the old command will first be removed from the 
command table. 

See the section "CLIM Command Tables". 



clim:add-gesture-name name type gesture-spec &key (-.unique t) Function 
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Adds a gesture named by the symbol name to the set of gesture names, type is the 
type of gesture being created, and must be one of the symbols described below. 
gesture-spec specifies the physical gesture that corresponds to the named gesture; 
its syntax depends on the value of type. 

If .-unique is t, an error is signalled if there is already a gesture named gesture- 
name. The default is nil. 

When type is rkeyboard, gesture-spec is a list of the form (key-name . modifier-key- 
names), key-name is the name of a non-modifier key on the keyboard (see below). 
modifier-key-names is a (possibly empty) list of modifier key names in the set 
rshift, rcontrol, :meta, rsuper or rhyper. 

For the standard Common Lisp characters (the 95 ASCII printing characters in- 
cluding #\Space), key-name is the character object itself. For the other "semi- 
standard" characters, key-name is a keyword symbol naming the character 
(rnewline, rlinefeed, rreturn, :tab, rbackspace, :page, and rrubout). 

When type is rpointer-button, gesture-spec is a list of the form (button-name . mod- 
ifier-key-names), button-name is the name of a pointer button (:left, rmiddle, or 
rright), and modifier-key-names is as above. 

See the section "Gestures and Gesture Names in CLIM". 



clim:add-keystroke-to-command-table command-table keystroke type value &key 
.■documentation (:errorp t) Function 

Adds a keystroke accelerator to the command-table. 

command-table 

Either a command table or a symbol that names a command table. 

keystroke A gesture spec that specifies the accelerator gesture. For applica- 
tions that have an interactor pane, this will typically correspond to 
a non-printing character, such as control -D, whose gesture spec is 
(:D : control). For applications that do not have an interactor pane, 
keystroke can correspond to a standard printing character as well, 
such as #\X. 

type When type is rcommand, value must be a command (a cons of a 

command name followed by a list of the command's arguments), or 
a command name. (When value is a command name, it behaves as 
though a command with no arguments was supplied.) In the case 
where all of the command's required arguments are supplied, typing 
the keystroke invokes the command immediately. Otherwise, the 
user will be prompted for the remaining required arguments. 

value Meaning depends on the value of type, as described above. 

.■documentation 

A documentation string, which can be used as documentation for 
the keystroke accelerator. 
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-.errorp If the command menu item associated with keystroke is already 
present in the command table's accelerator table and -.errorp is t, 
then the climrcommand-already-present condition will signalled. 
When the item is already present in the command table's accelera- 
tor table and .-errorp is nil, the old item will first be removed. 

The following example creates a keystroke accelerator for the com-next-frame on 

control -N. 

(def ine-debugger-command (com-next-frame :name t) 
((nframes 'integer 
: default 1 

:prompt "number of frames")) 
(next-frame : nframes nframes)) 

(cl im : add-keystroke-to-command-tabl e 

'debugger '(:n : control) : command '(com-next-frame 1)) 

See the section "CLIM's Keystroke Interaction Style". 



clim:add-menu-item-to-command-table command-table string type value &key .-doc- 
umentation (:after 'rend) .-keystroke .-text-style (.-errorp t) Function 

Adds a command menu item to command-table's menu. The arguments are: 

command-table 

Either a command table or a symbol that names a command table. 

string The name of the command menu item. The character case of string 
is ignored. This is how the item will appear in the menu. 

type One of: rcommand, rfunction, menu, or rdivider. When type is 

rcommand, value must be a command (a cons of a command name 
followed by a list of the command's arguments), or a command 
name. (When value is a command name, it behaves as though a 
command with no arguments was supplied.) In the case where all of 
the command's required arguments are supplied, clicking a com- 
mand menu item invokes the command immediately. Otherwise, the 
user will be prompted for the remaining required arguments. 

When type is menu, this item indicates that a sub-menu will be in- 
voked, and so value should be another command table or the name 
of another command table. 

When type is rfunction, value is a function of two arguments (the 
gesture and the accumulated numeric argument) that is called to 
generate a command object. 

When type is rdivider, some sort of a dividing line is displayed in 
the menu at that point. If the look-and-feel provided by the underly- 
ing window system has no corresponding concept, rdivider items 
may be ignored, value is ignored. If string is a string, it will be 
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used as the divider. Otherwise, string is only useful insofar as other 
calls to clim:add-menu-item-to-command-table may use it when 
rafter is supplied. 

value Meaning depends on the value of type, as described above. 

.■documentation 

A documentation string, which can be used as mouse documentation 
for the command menu item. 

.-after States where the command menu item should appear in the menu: 
either rstart, rend, nil, a string, or rsort. rstart means to add the 
new item to the beginning of the menu. A value of rend (the de- 
fault) or nil means to add the new item to the end of the menu. A 
string naming an existing entry means to add the new item after 
that entry. If rafter is rsort, then the item is inserted in such a 
way as to maintain the menu in alphabetical order. 

.■keystroke If supplied, the command menu item will be added to the command 
table's keystroke accelerator table. The value of .-keystroke must be 
a Common Lisp standard character or a gesture spec. This is exact- 
ly equivalent to calling climradd-keystroke-to-command-table with 
the arguments command-table, keystroke, type, and value. When 
.■keystroke is supplied and type is rcommand, typing the accelerator 
gesture will invoke the command specified by value. When type is 
rmenu, the command will continue to be read from the sub-menu 
indicated by value in a window system specific manner. 

■.text-style Allows you to specify the text style for any particular menu item. 

:errorp If the item named by string is already present in the command ta- 
ble's menu and :errorp is t, then the climrcommand-already- 
present condition will be signalled. When the item is already 
present in the command table's menu and :errorp is nil, the old 
item will first be removed from the menu. 

See the section "CLIM's Command Menu Interaction Style". 



climradd-output-record child record Generic Function 

Adds the output record child to the output record record, sets the parent of child 
to be record, and calls climrrecompute-extent-for-new-child to inform record of 
the new child. 

Any class that is a subclass of climroutput-record must implement this method. 

See the section "Concepts of CLIM Output Recording". 



clim-sysrall-processes Function 

Returns a sequence of all of the currently running processes. 
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climrallocate-pixmap medium width height Function 

Allocates and returns a pixmap object that can be used on any medium that shares 
the same characteristics as medium. (The exact definition of "shared characteris- 
tics" will vary from host to host.) medium can be a medium, a sheet, or a stream. 

The resulting pixmap will be at least width units wide, height units high, and as 
deep as is necessary to store the information for the medium. 

The returned value is the pixmap. 

See the section "Pixmaps in CLIM". 



clim-sys:allocate-resource name &rest parameters Function 

Allocates an object from the resource named name, using the parameters given by 
parameters, name is a symbol that names a resource. The returned value is the al- 
located object. 

See the section "Resources in CLIM". 



clim:allocate-space pane width height Generic Function 

During the space allocation pass, a composite pane arranges its children within the 
available space and allocates space to them according to their space requirements 
and its own composition rules by calling clim:allocate-space on each of the child 
panes, width and height are the width and height of pane in device units. 

clim:allocate-space is intended to be specialized by most pane classes. For exam- 
ple, the method for the class clim:vbox-pane allocates enough space for itself to 
hold all of its child panes in a vertical stack. 

See the section "Details of CLIM's Layout Algorithm". 



and &rest types Clim Presentation Type 

The presentation type that is used for multiple inheritance, and is usually used in 
conjunction with satisfies. For example, 

(and integer (satisfies oddp)) 

The elements of types can be presentation type abbreviations. 

The first type in types is in charge of accepting and presenting. The remaining el- 
ements of types are used for type checking (for example, filtering applicability of 
presentation translators). 

The and type has special syntax that supports the two "predicates" satisfies and 
not. satisfies and not cannot stand alone as presentation types and cannot be first 
in types, not can surround either satisfies or a presentation type. 



clinirapplication-frame Class 
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The protocol class that corresponds to a CLIM application frame. If you want to 
create a new class that obeys the application frame protocol, it must be a subclass 
of clim:application-frame. 



clim:*application-frame* Variable 

The current application frame. The global value is CLIM's default application. This 
variable is typically used in the bodies of commands and translators to gain access 
to the state variables of the application, usually in conjunction with clos:with-slots 
or clos:slot-value. 

This variable is bound by an raround method of clim:run-frame-top-level on 
clim:application-frame. You should not rebind it, since CLIM depends on its val- 
ue. 



clim:application-pane Class 

The pane class that is used to implement "application" panes. This is the type of 
pane created by clim:make-clim-application-pane, and corresponds to the pane 
type abbreviation : application in the rpanes clause of climrdefine-application- 
frame. The default method for climrframe-standard-output will return the first 
pane of this type in a frame. 

For clim:application-pane, the default for the :display-time option is rcommand- 
loop, and the default for the :scroll-bars option is :both. 

See the section "Using the rpanes Option to climrdefine-application-frame". 



clim:application-frame-p object Function 

Returns t if and only if object is of type climrapplication-frame. 



climrapply-presentation-generic-function presentation-function-name &body argu- 
ments Macro 

Applies the presentation generic function presentation-function-name to arguments 
arguments using apply. 

The presentation-function-name argument is not evaluated. The value of presenta- 
tion-function-name can be any of the presentation generic functions defined by 
CLIM (climraccept, climrpresent, clim:describe-presentation-type, 

clim:presentation-typep, climrpresentation-subtypep, 

climraccept-present-default, clim:presentation-type-specifier-p, 

clim:presentation-refined-position-test, or climrhighlight-presentation) or any 
presentation generic function you have defined yourself. 



climrarea Class 
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This is a subclass of climrregion that denotes regions that have dimensionality 2 
(that is, have area). If you want to create a new class that obeys the area protocol, 
it must be a subclass of climrarea. 

Making an climrarea object with no area canonicalizes it to clim:+nowhere+. 



climrareap object Generic Function 

Returns t if and only if object is of type climrarea. 

climrarmed-callback gadget client id Generic Function 

This callback is invoked when the gadget gadget is armed. The exact definition of 
arming varies from gadget to gadget, but typically a gadget becomes armed when 
the pointer is moved into its region. 

The default method for climrarmed-callback (on climrbasic-gadget) calls the func- 
tion specified by the rarmed-callback initarg. 

See the section "Using Gadgets in CLIM". 

climr+background-ink+ Constant 

An indirect ink that uses the medium's background design. See the section "Indi- 
rect Ink in CLIM". 

climrbasic-gadget Class 

The implementation class on which many CLIM gadgets are built. 

climrbeep &optional (stream *standard-output*J Function 

Attracts the user's attention, usually with an audible sound. 

climrblank-area Presentation Type 

The presentation type that represents all the places in a window where there is no 
applicable presentation. CLIM provides a single "null presentation" (represented 
by the value of climr*null-presentation*) of this type. 

climrboolean Clim Presentation Type 

The presentation type that represents t or nil. The textual representation is "Yes" 
and "No", respectively. 

climrbounding-rectangle* region Generic Function 
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Returns the bounding rectangle of region as four real numbers that specify the 
left, top, right, and bottom edges of the bounding rectangle, region must be a 
bounded region, such as an output record, a sheet or window, or a geometric ob- 
ject such as a line or an ellipse. 

The coordinates of the bounding rectangle of sheets and output records are main- 
tained relative to the parent of the sheet or output record. 

See the section "Bounding Rectangles in CLIM". 



climrbounding-rectangle Class 

The protocol class that corresponds to a bounding rectangle. If you want to create 
a new class that obeys the bounding rectangle protocol, it must be a subclass of 
climrbounding-rectangle. 



climrbounding-rectangle region Generic Function 

Returns a new bounding rectangle for region as a climrstandard-bounding- 
rectangle object, region is as for climrbounding-rectangle*. 



climrbounding-rectangle-bottom region Function 

Returns the coordinate of the bottom edge of the bounding rectangle of region, re- 
gion is as for climrbounding-rectangle*. 



climrbounding-rectangle-height region Function 

Returns the height of the bounding rectangle of region, region is as for 
climrbounding-rectangle*. 



climrbounding-rectangle-left region Function 

Returns the coordinate of the left edge of the bounding rectangle of region, region 
is as for climrbounding-rectangle*. 



climrbounding-rectangle-max-x region Generic Function 

Returns the coordinate of the right edge of the bounding rectangle of region. In 
Symbolics CLIM 2.0, this is the same thing as climrbounding-rectangle-left. 



climrbounding-rectangle-max-y region Generic Function 

Returns the coordinate of the bottom edge of the bounding rectangle of region. In 
Symbolics CLIM 2.0, this is the same thing as climrbounding-rectangle-bottom. 
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clim:bounding-rectangle-min-x region Generic Function 

Returns the coordinate of the left edge of the bounding rectangle of region. In 
Symbolics CLIM 2.0, this is the same thing as clim:bounding-rectangle-left. 



clim:bounding-rectangle-min-y region Generic Function 

Returns the coordinate of the top edge of the bounding rectangle of region. In 
Symbolics CLIM 2.0, this is the same thing as clim:bounding-rectangle-top. 



clim:bounding-rectangle-p object Function 

Returns t if and only if object is of type climrbounding-rectangle. 

climrbounding-rectangle-position region Generic Function 

Returns the position of the bounding rectangle of region as two values, the left 
and top coordinates of the bounding rectangle. 

The coordinate system of the position returned by climrbounding-rectangle- 
position depends on the type of region. If region is an output record, the position 
will be relative to the parent output record of region. If region is a subclass of 
climrregion, the position will be an "absolute" position. 

clim:bounding-rectangle-right region Function 

Returns the coordinate of the right edge of the bounding rectangle of region, re- 
gion is as for climrbounding-rectangle*. 

clim:bounding-rectangle-set-position region x y Generic Function 

Changes the position of the bounding rectangle of region to the new position x and 
y. x and y are the new left and top coordinates of the bounding rectangle. 

The coordinate system of x and y depends on the type of region. If region is an 
output record, x and y should be relative to the parent output record of region. If 
region is a subclass of climrregion, x and y should be an "absolute" position. 

clim:bounding-rectangle-size region Function 

Returns the size (as two values, width and height) of the bounding rectangle of re- 
gion, region is as for climrbounding-rectangle*. 

climrbounding-rectangle-top region Function 

Returns the coordinate of the top edge of the bounding rectangle of region, region 
is as for climrbounding-rectangle*. 
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clim:bounding-rectangle-width region Function 

Returns the width of the bounding rectangle of region, region is as for 
climrbounding-rectangle*. 



clim:bury-frame frame Generic Function 

Buries the application frame frame so that it is underneath all of the other host 
windows. clim:bury-frame works by calling clim:bury-sheet on the frame's top- 
level sheet. This does not change the state of the frame. 



clim:call-presentation-menu presentation input-context frame window x y &key 
(:for-menu t) .-label Function 

Finds all the applicable translators for presentation in the input context input- 
context, creates a menu that contains all of the translators, and pops up a menu 
from which the user can choose a translator. After the translator is chosen, it is 
called and the values are returned to the appropriate call to clim:with-input- 
context. 

frame, window, x, and y are as for climrfind-applicable-translators. :for-menu, 
which defaults to t, is used to decide which presentation translators go in the 
menu (the value of their :menu option must match :for-menu). -.label is used as a 
label for the menu, and defaults to nil, meaning the menu will not be labelled. 

See the section "Low Level Functions for CLIM Presentation Translators". 

For example, CLIM's "menu" translator could be defined as follows: 

(cl im:def ine-presen tat ion-act ion presentation-menu 
(t nil cl im: presentation-menu-command-table 
: documentation "Menu" 

:menu nil ;this doesn't go into any menu 

:gesture :menu) 
(presentation frame window x y) 
(cl im:cal 1 -presentation-menu presentation cl im:*input-contextx 

frame window x y 
:for-menu t)) 



climrcall-presentation-translator translator presentation context-type frame event 
window x y Function 

Calls the function that implements the body of translator on presentation's, object, 
and passes presentation, context-type, frame, event, window, x, and y to the body of 
the translator as well. 

frame, window, x, and y are as for climrfind-applicable-translators. context-type is 
the presentation type for the context that matched, event is the event correspond- 
ing to the user's gesture. 
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The returned values are the same as the values returned by the body of the trans- 
lator, which should be the translated object and the translated type. 

See the section "Low Level Functions for CLIM Presentation Translators". 



clim:catch-abort-gestures (format-string &rest format-args) &body body Macro 

clim:catch-abort-gestures is a convenient macro that you can use in the top level 
loop of an application (or in any call to climraccept) that establishes a restart for 
conditionsrabort and a handler for climrabort-gesture, and then evaluates body, 
format-string and format-args are used in conditionsrabort restart. 

This macro could be written as follows: 

(defun handle-abort-gesture (condition) 
(declare (ignore condition)) 
(abort)) 

(def macro catch-abort-gestures ((format-string &rest format-args) &body body) 
1 (condi ti ons : wi th-si mpl e- restart 

(abort , format-string ,@format-args) 
(conditions: handler-bind 

((cl im: abort-gesture #' handle-abort-gesture)) 
,§body))) 

The top level loop of an application could use this as follows: 

(loop 

(cl im : catch-abort-gestures 

("Return to ~A command level" (cl im: frame-pretty-name frame)) 
(cl im: redisplay- frame-panes frame) 
(when interactor 

(fresh-line xstandard-inputx) 
(write-string prompt xstandard-inputx)) 
(let ((command (cl im: read-frame-command frame : stream command-stream))) 
(when interactor 

(terpri xstandard-inputx)) 
(when command 

(cl im: execute-frame-command frame command))))) 



character Clim Presentation Type 

The presentation type that represents a Common Lisp character object. 

clim:check-box Class 

A check box is similar to a radio box: it is a special kind of gadget that contains 
one or more toggle buttons. At any one time, zero or more of the buttons managed 
by the check box may be "on". The contents of a check box are its buttons, and as 
such a check box is responsible for laying out the buttons that it contains. 
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It is a subclass of climrvalue-gadget and clim:oriented-gadget-mixin. 

See the section "Using Gadgets in CLIM". 

In addition to the initargs for climrvalue-gadget and the usual pane initargs 
(rforeground, rbackground, rtext-style, space requirement options, and so forth), 
the following initargs are supported: 

rselectionThis is used to specify which button, if any, should be initially se- 
lected. 

rchoices This is used to specify all of the buttons that serve as choices. 

As the user changes the selections, the newly selected (or deselected) button will 
have its climrvalue-changed-callback handler invoked. 

Calling climrgadget-value on a check box will return a sequence of the currently 
selected toggle buttons. The value of the check box can be changed by calling setf 
on climrgadget-value. 

A check box might be created as follows, although it is generally more convenient 
to use climrwith-radio-box: 

(let* ((choices 

(list (cl im: make-pane 'cl im: toggle-button 
: label "One" :width 80) 
(cl im: make-pane 'cl im: toggle-button 

: label "Two" :width 80) 
(cl im: make-pane 'cl im: toggle-button 
: label "Three" :width 80))) 
(current (second choices))) 
(cl im:make-pane 'cl im:check-box 
:choices choices 
selection (list current) 
: val ue-changed-cal 1 back ' radi o-val ue-changed-cal 1 back) ) 

(defun radi o-val ue-changed-cal 1 back (radio-box value) 
(declare (ignore radio-box)) 
(format t "~&Radio box toggled to ~S" value)) 



climrcheck-box-current-selection check-box Generic Function 

Returns a sequence of the currently selected items in the check box. Each of the 
selections will be one of the toggle buttons in the check box. 

You can use setf on this in order to set the current selection for the check box, or 
you can use setf on climrgadget-value of the check box to accomplish the same 
thing. 



climrcheck-box-selections check-box Generic Function 
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Returns a sequence of all of the selections in the check box. The elements of the 
sequence will be toggle buttons. 



clim:check-box-view Class 

The class that represents the view corresponding to a check box. This is usually 
used for a "some of" choice, such as a climrsubset presentation type. 



clim:+check-box-view+ Constant 

An instance of the class clim:check-box-view. 

climrclear-output-record record Generic Function 

Removes all of the child output records from the output record record. 

Any class that is a subclass of climroutput-record must implement this method. 

clim-sys:clear-resource resource Function 

Clears the resource named name, that is, removes all of the resourced objects from 
the resource, name is a symbol that names a resource. 

See the section "Resources in CLIM". 

clim:clim-stream-pane Class 

This class implements a pane that supports the CLIM graphics, extended input and 
output, and output recording protocols. Most non-gadget application panes are sub- 
classes of this class, including clim:application-pane and clim:interactor-pane. 

See the section "Panes in CLIM". 

climrclose stream &key .-abort Generic Function 

In CLIM, close is defined as a generic function. Otherwise, it behaves the same as 
the normal Common Lisp close function. 

climrcolor Class 

A color is a completely opaque design that represents the intuitive definition of 
color (such as white, black, red, or pale yellow), climrcolor is the class that repre- 
sents colors in CLIM. 

clim:color-ihs color Generic Function 
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Returns three values, the intensity, hue, and saturation components of color. The 
first value is a real number between and the square root of 3 (inclusive). The 
second and third values are real numbers between and 1 (inclusive). 



clim:color-rgb color Generic Function 

Returns three values, the red, green, and blue components of color. The values are 
real numbers between and 1 inclusive. 



climrcolorp object Function 

Returns t if and only if object is of type climrcolor. 

climrcommand &key : command-table Clim Presentation Type 

The presentation type used to represent a CLIM command processor command and 
its arguments, .-command-table can be either a command table or a symbol that 
names a command table. 

If .-command-table is not supplied, it defaults to the command table for the current 
application, that is, (clim:frame-command-table clim:*application-frame*). 

When you call climraccept on this presentation type, the returned value is a list; 
the first element is the command name, and the remaining elements are the com- 
mand arguments. You can use clim:command-name and climrcommand- 
arguments to access the name and arguments of the command object. 

For more information about CLIM command objects, see the section "Command 
Objects in CLIM". 



clim:command-accessible-in-command-table-p command-name command-table 

Function 

If the command named by command-name is not accessible in command-table, then 
this function returns nil. Otherwise, it returns the command table in which the 
command was found, command-table may be either a command table or a symbol 
that names a command table. 

A command is present in a command table when it has been added to that com- 
mand table. A command is accessible in a command table when it is present in 
that command table or is present in any of the command tables from which that 
command table inherits. 



climrcommand-already-present Condition 

A condition that is signalled when a command is already present in the command 
table in functions such as clim:add-command-to-command-table. 
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climrcommand-arguments command Function 

Given a command object command, returns the command's arguments. 

climr*command-dispatchers* Variable 

This is a list of characters that indicate that CLIM should read a command when 
CLIM is accepting input of type clim:command-or-form. The default value for this 
is colon ( tt\ : ) . 



climrcommand-enabled command-name frame &optional command-table 

Generic Function 

Returns t if the command named by command-name is presently enabled in com- 
mand-table for the frame frame, otherwise returns nil. If command-name is not ac- 
cessible in command-table, climrcommand-enabled will return nil. command-table 
defaults to the current command table for frame. 

You can use setf on climrcommand-enabled in order to enable or disable a com- 
mand. 



climrcommand-line-command-parser command-table stream Function 

Reads a command line on behalf of an application frame's command loop. User 
programs should not call this function explicitly, but should rather bind 
climr*command-parser* to it. 

This is the function CLIM uses to parse commands in a command-line driven in- 
terface. 



climrcommand-line-command-unparser command-table stream args-to-go &rest 
keys &key :for-context-type (.-acceptably t) &allow-other-keys Function 

"Unparses" a command line on behalf of an application frame's command loop. 
User programs should not call this function explicitly, but should rather bind 
climr*command-unparser* to it. 



climrcommand-line-name-for-command command-name command-table &key (:er- 
rorp t) Function 

Returns the command-line name for command-name as it is installed in command- 
table. If the command is not accessible in command-table (or the command has no 
command-line name and :errorp is t), then the climrcommand-not-accessible con- 
dition is signalled. 

If the command does not have a command-line name in the command-table and :er- 
rorp is rcreate, then the returned value will be an automatically created command- 
line name. 
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command-table may be either a command table or a symbol that names a command 
table. 

This function is the inverse of clim:find-command-from-command-line-name. 



clim:command-line-read-remaining-arguments-for-partial-command partial- 

command command-table stream start-location &key :for-accelerator Function 

Reads the remaining arguments of a partial command line on behalf of an applica- 
tion frame's command loop. User programs should not call this function explicitly, 
but should rather bind clim:*partial-command-parser* to it. 



clim:command-menu-enabled command-table frame Generic Function 

Returns t if the command table command-table is presently enabled in the com- 
mand menu for the frame frame, otherwise returns nil. 

You can use setf on clim:command-menu-enabled in order to enable or disable a 
command table in the command menu for frame. 

This function is like climrcommand-enabled, except that it operates only on the 
:menu items in a command table's menu for a particular frame. 



clim:command-menu-item-options item Function 

Returns a property list of the options for the command menu item item. Currently, 
the only option is :text-style, which specifies what text style the item should be 
displayed in. 



clim:command-menu-item-type item Function 

Returns the type of the command menu item item. This will be one of rcommand, 
rfunction, menu, or rdivider. 



clim:command-menu-item-value item Function 

Returns the value of the command menu item item. For example, if the type of 
item is rcommand, this will return a command or a command name. 



clim:command-menu-pane Class 

The pane class that is used to implement command menu panes (but not menu 
bars). It corresponds to the pane type abbreviation :command-menu in the rpanes 
clause of clim:define-application-frame. The default display function for panes of 
this type is clim:display-command-menu. 

For clim:command-menu-pane, the default for the :display-time option is 
:command-loop, the default for the rincremental-redisplay option is t, and the de- 
fault for the :scroll-bars option is nil. 
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Note that many applications will not use any panes of this type, since most frame 
managers automatically provide a menu bar for the frame. 



clim:command-name command Function 

Given a command object command, returns the command name. 

clim:command-name cfekey : command-table Clim Presentation Type 

The presentation type used to represent the name of a CLIM command processor 
command in the command table : command-table. 

: command-table may be either a command table or a symbol that names a com- 
mand table. If : command-table is not supplied, it defaults to the command table for 
the current application. The textual representation of a clim:command-name ob- 
ject is the command-line name of the command, while the internal representation 
is the command name. 

clim:command-name-from-symbol symbol Function 

Generates a string suitable for use as a command line name from the symbol sym- 
bol. The string consists the symbol name with the hyphens replaced by spaces, and 
the words capitalized. If the symbol name is prefixed by "com-", the prefix is re- 
moved. For example, if the symbol is com-show-file, the resulting string will be 

"Show File". 

clim:command-not-accessible Condition 

A condition that is signalled when the command you are looking for is not accessi- 
ble in the command table, for example, clim:find-command-from-command-line- 
name. 

clim:command-not-present Condition 

A condition that is signalled when the command you are looking for is not present 
in the command table. 

clim:command-or-form &key : command-table Clim Presentation Type 

The presentation type used to represent either a Lisp form or a CLIM command 
processor command and its arguments. In order for the user to indicate that he 
wishes to enter a command, a command dispatch character must be typed as the 
first character of the command line. 

See the variable clim:*command-dispatchers*. 

: command-table may be either a command table or a symbol that names a com- 
mand table. If : command-table is not supplied, it defaults to the command table for 
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the current application, that is, (clim:frame-command-table clim:*application- 
frame*). 



clim:*command-parser* Variable 

The currently active command parsing function. 

The default for this is clim:command-line-command-parser when there is at least 
one interactor pane in the application frame, otherwise the default is climrmenu- 
command-parser. 

If you want a dialog-driven command processing loop, you can use the parsing 
function climraccept-values-command-parser. 



clim:command-present-in-command-table-p command-name command-table 

Function 

Returns t if command-name is present in command-table. 

A command is present in a command table when it has been added to that com- 
mand table. A command is accessible in a command table when it is present in 
that command table or is present in any of the command tables from which that 
command table inherits. 



clim:command-table Class 

The class that represents command tables. 

clim:command-table-already-exists Condition 

This condition is signalled by clim:make-command-table when you try to create a 
command table that already exists. 

clim:command-table-inherit-from command-table Generic Function 

Returns a list of all of the command tables from which command-table inherits. 
You can setf this in order to change the inheritance of command-table. 

clim:command-table-name command-table Generic Function 

Returns the name of the command table command-table. 

clim:command-table-not-found Condition 

This condition is signalled by functions such as clim:find-command-table when 
the named command table cannot be found. 
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clim:*command-unparser* Variable 

The currently active command unparsing function. 

The default for this is clim:command-line-command-unparser when there is at 
least one interactor pane in the application frame, otherwise there is no command 
unparser. 

clim-sys:current-process Function 

Returns the currently running process, which will be a process object. 
See the section "Multi-processing in CLIM". 



clim:complete-from-generator string generator delimiters &key (.-action rcomplete) 
.■predicate Function 

Given an input string string and a list of delimiter characters delimiters that act 
as partial completion characters, clim:complete-from-generator completes against 
the possibilities that are generated by the function generator, generator is a func- 
tion of two arguments, the string string and another function that it calls in order 
to process the possibility. 

.■action must be one of rcomplete, rcomplete-maximal, rcomplete-limited, or 
rpossibilities. See the function clim:complete-input. 

.■predicate is nil or a function of one argument, an object. If the predicate returns 
t, the possibility corresponding to the object is processed, otherwise it is not. You 
can supply this when you want to prevent some objects from being part of the 
completion set. 

clim:complete-from-generator returns five values, the completed input string, the 
success value (t if the completion was successful, otherwise nil), the object match- 
ing the completion (or nil if unsuccessful), the number of matches, and a list of 
possible completions if .-action was rpossibilities. 

You might use clinirconiplete-from-generator inside the climraccept method for a 
cardinal number presentation type as follows: 

(let ((possibilities '(("One" 1) ("Two" 2) ("Three" 3)))) 
(flet ((generator (string suggester) 
(declare (ignore string)) 
(dolist (possibility possibilities) 

(funcall suggester (first possibility) (second possibility))))) 
(cl im: complete- input 
stream 
#' (lambda (string action) 

(cl im : compl ete-f rom-generator 
string ^'generator nil 
:action action))))) 
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clim:complete-from-possibilities string completions delimiters &key (.-action 
rcomplete) .-predicate (:name-key #'first) (:value-key #'second) Function 

Given an input string string and a list of delimiter characters delimiters that act 
as partial completion characters, clim:complete-from-possibilities completes 
against the possibilities in the sequence (a list or a vector) completions. 

The completion string is extracted from the possibilities in completions by applying 
-.name-key . The object is extracted by applying -.value-key . 

-.action must be one of rcomplete, rcomplete-maximal, rcomplete-limited, or 
rpossibilities. See the function clim:complete-input. 

-.predicate is either nil or a function of one argument, an object. If the predicate 
returns t, the possibility corresponding to the object is processed, otherwise it is 
not. You can supply this when you want to prevent some objects from being part 
of the completion set. 

clim:complete-from-possibilities returns five values, the completed input string, 
the success value (t if the completion was successful, otherwise nil), the object 
matching the completion (or nil if unsuccessful), the number of matches, and a list 
of possible completions if -.action was rpossibilities. 

You might use clim:complete-from-possibilities inside the climraccept method for 
a cardinal number presentation type as follows: 

(let ((possibilities '(("One" 1) ("Two" 2) ("Three" 3)))) 
(cl im: complete- input 
stream 
#' (lambda (string action) 

(cl im:complete-f rom-possibil ities 
string possibilities nil 
:action action)))) 



climrcomplete-input stream function &key -.partial-completers :allow-any-input .-pos- 
sibility-printer (:help-displays-possibilities t) Function 

Reads input from stream, completing from a set of possibilities. 

function is a function of two arguments which is called to generate the possibili- 
ties. Its first argument is a string containing the input so far. Its second argument 
is the completion mode, one of the following: 

• rcomplete — Completes the input as much as possible, except that if the 
user's input exactly matches one of the possibilities, even if it is a left 
substring of another possibility, the shorter possibility is returned as the 
result. 

• rcomplete-limited — Completes the input up to the next partial delim- 
iter. 

• rcomplete-maximal — Completes the input as much as possible. 
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• rpossibilities — Causes clim:complete-input to return a list of the possi- 
ble completions. 

function must return five values: 

• string — The completed input string. 

• success — t if completion was successful (otherwise nil). 

• object — The accepted object (nil if unsuccessful). 

• nmatches — The number of possible completions of the input. 

• possibilities — An alist of completions ((string object) ...), returned only 
when the completion mode is rpossibilities. 

climrcomplete-input returns three values: object, success, and string. 

.■partial-completers is a (possibly empty) list of characters that delimit portions of a 
name that can be completed separately. The default is an empty list. Typical par- 
tial completers are spaces and dashes. 

If -.allow -any -input is t, climrcomplete-input will return as soon as the user types 
an activation gesture, even if the input is not any of the possibilities. The default 
is nil. Use this when you want to complete from a set of existing objects, but want 
to allow the user to enter a new object. 

If -.possibility-printer is supplied, it must be a function of three arguments: a possi- 
bility, a presentation type, and a stream. The function should display the possibili- 
ty on the stream. The possibility will be a list of two elements, the first being a 
string and the second being the object corresponding to the string. 

If :help-display-possibilities is t (the default), then when the user types a help ges- 
ture (one of the gestures in climr*help-gestures*), CLIM will display all the 
matching possibilities. If nil, then CLIM will not display the possibilities unless 
the user types a possibility gesture (one of the gestures in climr*possibilities- 
gestures*). 



climrcompleting-from-suggestions (stream &rest options &key .-partial-completers 
:allow-any-input .-possibility-printer (:help-displays-possibilities t)) &body body Macro 

Reads input from stream, completing from a set of possibilities generated by calls 
to climrsuggest in body. Returns three values: object, success, and string. 

.-partial-completers, :allow-any-input, .-possibility-printer, and :help-displays- 
possibilities are as for climrcomplete-input. 

You could use the following in a climraccept method for cardinal numbers. 
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(cl im:completing-f rom-suggestions (stream) 
(map nil 

#'(lambda(x) 

(cl im:suggest (car x) (cdr x))) 
'(("One" . 1) 

("Two" . 2) 

("Three" . 3)))) 



climrcompletion sequence &key :test :value-key Clim Presentation Type 

The presentation type that selects one from a finite set of possibilities, with 
"completion" of partial inputs. Several types are implemented in terms of the 
climrcompletion type, including clim:token-or-type, clim:null-or-type, member, 
climrmember-sequence, and clim:member-alist. 

The presentation type parameters are: 

sequence A list or vector whose elements are the possibilities. Each possibili- 
ty has a printed representation, called its name, and an internal 
representation, called its value, climraccept reads a name and re- 
turns a value, climrpresent is given a value and outputs a name. 

-.test A function that compares two values for equality. The default is 

eql. 

:value-key A function that returns a value given an element of sequence. The 
default is identity. 

The following presentation type options are available: 

:name-key 

A function that returns a name, as a string, given an element of se- 
quence. The default is a function that behaves as follows: 



Argument 


Returned Value 


string 


the string 


null 


the string "NIL" 


cons 


string of the car 


symbol 


string-capitalize of its name 


otherwise 


princ-to-string of it 



: documentation-key 

A function that returns nil or a descriptive string, given an element 
of sequence. The default always returns nil. 

rpartial-completers 

A (possibly empty) list of characters that delimit portions of a name 
that can be completed separately. The default is a list of one char- 
acter, ttsSpace. 
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clim:*completion-gestures* Variable 

A list of gesture names that cause clim:complete-input to complete the input as 
fully as possible. On most systems, this includes the gesture corresponding to the 
ttMab character. On Genera, it includes the gesture for ttsConplete as well. 



complex &optional type Clim Presentation Type 

The presentation type that represents a complex number. It is a subtype of 
number. 

type is the type to use for the components. It must be a subtype of real. 



clim:compose-in designl design2 Generic Function 

Composes a design by using the color (or ink) of designl and clipping to the inside 
of design2. That is, design2 specifies the mask to use for changing the shape of 
the design. 

More precisely, at each point in the drawing plane the resulting design specifies a 
color and an opacity as follows: the color is the ink of designl. The opacity is the 
opacity of designl, multiplied by the stencil opacity of design2. 

The stencil opacity of a design at a point is defined as the opacity that would re- 
sult from drawing the design onto a fictitious medium whose drawing plane is ini- 
tially completely transparent black (opacity and all color components are zero), and 
whose foreground and background are both opaque black. (With this definition, the 
stencil opacity of a member of class climropacity is simply its value.) 

If design2 is a solid design, the effect of clim:compose-in is to clip designl to de- 
sign2. If design2 is translucent, the effect is a soft matte. 

If both arguments are regions, clim:compose-in is the same as climrregion- 
intersection. 

The result returned by clim:compose-in might be freshly constructed or might be 
an existing object. 

See the section "Drawing with Designs in CLIM". 



clim:compose-out designl design2 Generic Function 

Composes a design by using the color (or ink) of designl and clipping to the out- 
side of design2. That is, design2 specifies the mask to use for changing the shape 
of the design. 

More precisely, at each point in the drawing plane the resulting design specifies a 
color and an opacity as follows: the color is the ink of designl. The opacity is the 
opacity of designl, multiplied by 1 minus the stencil opacity of design2. 

If design2 is a solid design, the effect of clim:compose-out is to clip designl to the 
complement of design2. If design2 is translucent, the effect is a soft matte. 
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If both arguments are regions, clim:compose-out is the same as climrregion- 
difference. 

The result returned by clim:compose-out might be freshly constructed or might 
be an existing object. 

See the section "Drawing with Designs in CLIM". 



clim:compose-over designl design2 Generic Function 

Composes a design that is equivalent to designl drawn on top of design2. Drawing 
the resulting design produces the same visual appearance as drawing design2 and 
then drawing designl, but might be faster and might not allow the intermediate 
state to be visible on the screen. 

If both arguments are regions, clim:compose-over is the same as climrregion- 
union. 

The result returned by clim:compose-over might be freshly constructed or might 
be an existing object. 

See the section "Drawing with Designs in CLIM". 



clim:compose-rotation-with-transformation transform angle &optional origin 

Generic Function 

Creates a new transformation by composing transform with a given rotation, as 
specified by angle and origin, angle is in radians. If origin is supplied it must be a 
point; if not supplied it defaults to (0,0). The order of composition is that the rota- 
tion "transformation" is first, followed by transform. 

This function could have been implemented as follows: 

(def un compose- rotati on-wi th-transf ormati on 
(transform angle &optional origin) 
(cl im: compose- transformations 
transform 
(cl im:make-rotation-transformation angle origin))) 



clim:compose-scaling-with-transformation transform mx my &optional origin 

Generic Function 

Creates a new transformation by composing transform with a given scaling, as 
specified by mx, my, and origin. If origin is supplied it must be a point; if not sup- 
plied it defaults to (0,0). The order of composition is that the scaling "transfor- 
mation" is first, followed by transform. 

This function could have been implemented as follows: 
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(defun compose-scal ing-with-transformation 
(transform mx my &optional origin) 
(cl im: compose- transformations 
transform 
(cl im:make-scal ing-transformation mx my origin))) 



clim:compose-space pane &key .-width .-height Generic Function 

During the space composition pass, a composite pane queries each of its children 
to find out how much space they requires by calling clim:compose-space. Each 
child pane answers by returning a climrspace-requirement object. The composite 
then forms its own space requirement by composing the space requirements of its 
children according to its own rules for laying out its children. 

The value returned by clim:compose-space is a space requirement object that rep- 
resents how much space the pane pane requires for itself and its children. 

.-width and .-height are real numbers that the clim:compose-space method for a 
pane may use as "recommended" values for the width and height of the pane. 
These are used to drive top-down layout, such as occurs when the overall size for 
a frame is explicitly supplied. 

clim:compose-space is intended to be specialized by most pane classes. For exam- 
ple, the method for the class clim:vbox-pane requests enough space for itself to 
hold all of its child panes in a vertical stack. 

See the section "Details of CLIM's Layout Algorithm". 



clim:compose-transformation-with-rotation transform angle &optional origin 

Generic Function 

Creates a new transformation by composing the rotation given by angle and origin 
with transform. The order of composition is that transform is first, followed by the 
rotation "transformation". The angle is specified in radians. If origin is supplied it 
must be a point; if not supplied it defaults to (0,0). 



clim:compose-transformation-with-scaling transform mx my &optional origin 

Generic Function 

Creates a new transformation by composing the scaling given by mx, my, and ori- 
gin with transform. The order of composition is that transform is first, followed by 
the scaling "transformation". Multiplies the X-coordinate distance of every point 
from origin by mx and the Y-coordinate distance of every point from origin by my. 
If origin is supplied it must be a point; if not supplied it defaults to (0,0). 



clim:compose-transformation-with-translation transform dx dy Generic Function 
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Creates a new transformation by composing the translation given by dx and dy 
with transform. The order of composition is that transform is first, followed by the 
translation "transformation", dx gives the amount to translate in the X direction, 
and dy gives the amount to translate in the Y direction. 



climrcompose-transformations transforml transform2 Generic Function 

Returns a transformation that is the composition of its arguments. Composition is 
in right-to-left order, that is, the resulting transformation represents the effects of 
applying transform2 followed by transforml. This is consistent with the order in 
which climrwith-translation, climrwith-rotation, and climrwith-scaling compose. 
For example, the following two forms result in the same transformation, presum- 
ing that the stream's transformation is the identity transformation: 

(cl im: compose- transformations 

(cl im: make-translation-transformation dx dy) 
(cl im: make- rotation- transformation angle)) 

(cl im:with-translation (stream dx dy) 
(cl im:with-rotation (stream angle) 
(cl im: medium- transformation stream))) 

Any arbitrary transformation can be built up by composing a number of simpler 
transformations, but that composition is not unique. 



clim:compose-translation-with-transformation transform dx dy Generic Function 

Creates a new transformation by composing transform with a given translation, as 
specified by dx and dy. The order of composition is that the translation "transfor- 
mation" is first, followed by transform. 

This function could have been implemented as follows: 

(defun compose- t r ansl at ion-with- transformation 
(transform dx dy) 
(cl im: compose- transformations 
transform 
(cl im:make-translation-transformation dx dy))) 



clim:contrasting-dash-patterns-limit port Generic Function 

Returns the number of contrasting dash patterns that the port port can generate. 
On most ports, this number is presently 16. 



clim:contrasting-inks-limit port Generic Function 
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Returns the number of contrasting inks that the port port can generate. On most 
ports, this number is presently 8. 



clim:+control-key+ Constant 

The modifier state bit that corresponds to the user holding down the control key 
on the keyboard. See the section "Operators for Gestures in CLIM". 



clim:convert-from-absolute-to-relative-coordinates stream output-record Function 

Returns the X and Y offsets that map the "absolute" coordinates of an output 
record to parent-relative coordinates. This is the inverse of clim:convert-from- 
relative-to-absolute-coordinates. 



clim:convert-from-relative-to-absolute-coordinates stream output-record Function 

The coordinates of output records in CLIM are maintained so that each record's 
coordinates are relative to its parent. Many CLIM functions, such as climrreplay- 
output-record, must compute the absolute coordinates of a record in order to work 
properly. See the section "Output Recording in CLIM". 

clim:convert-from-relative-to-absolute-coordinates returns the X and Y offsets 
that map the parent-relative coordinates of an output record to "absolute" coordi- 
nates. 

Here is an example of using climrreplay-output-record in a way that maintains 
the X and Y offsets correctly: 

(multiple-value-bind (x-offset y-offset) 

(cl i m : convert- f rom-rel ati ve-to-absol ute-coordi nates 
stream (cl im: output-record-parent record)) 
(cl im: repl ay-output-record record stream region x-offset y-offset)) 

The following function will map over all of the descendants of an output record 
that overlap a given region: 
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(defun map-over-output- record- tree 

(function record &optional (region cl im:+everywhere+)) 
(declare (dynamic-extent function)) 
(labels ((map-internal (rec x-offset y-offset) 
(multiple-value-bind (xoff yoff) 

(cl im:output-record-position rec) 
(cl im: translate-coordi nates x-offset y-offset xoff yoff) 
(unless (eql rec record) ;not the first time 

(funcall function rec)) 
(cl im: map-over-output- records-over lapping- region 
tt'map-internal rec region 
(- x-offset) (- y-offset) xoff yoff)))) 
(declare (dynamic-extent tf'map-internal )) 
(multiple-value-bind (x-offset y-offset) 

(cl i m : convert- f rom-rel ati ve-to-absol ute-coordi nates 
nil (output-record-parent record)) 
(map-internal record x-offset y-offset)))) 



climrcoordinate Type Specifier 

The type used by CLIM to represent a coordinate. This will be either t or a sub- 
type of real. 

In Symbolics CLIM, the climrcoordinate type is currently the same as real, but 
some implementations might use a more restricted type such as fixnum. 



climrcoordinate x Function 

Converts the real number x to a userrrclim-coordinate object. 



climrcopy-area medium from-x from-y width height to-x to-y &optional (op boole-lj 

Generic Function 

Copies the pixels from the medium medium starting at the position specified by 
(from-x,from-y) to the position (to-x,to-y) on the same medium. A rectangle whose 
width and height is specified by width and height is copied, from-x, from-y, to-x, 
and to-y are specified in user coordinates. (If medium is a sheet or a stream, then 
from-x and from-y are transformed by the user transformation.) 

op is a boolean operation that controls how the source and destination bits are 
combined. It defaults to boole-1, that is, the source bits are copied unchanged into 
the destination. Other useful values for op are boole-ior, boole-xor, and boole-clr. 



See the section "Pixmaps in CLIM". 



climrcopy-from-pixmap pixmap pixmap-x pixmap-y width height medium medium-x 
medium-y &optional (op boole-lj Function 
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Copies the pixels from the pixmap pixmap starting at the position specified by 
(pixmap-x,pixmap-y) into the medium medium at the position (medium-x,medium-y). 
A rectangle whose width and height is specified by width and height is copied. 
medium-x and medium-y are specified in user coordinates. (If medium is a sheet or 
a stream, then medium-x and medium-y are transformed by the user transforma- 
tion.) 

pixmap must be an object returned by climrallocate-pixmap that has the appropri- 
ate characteristics for medium. 

op is a boolean operation that controls how the source and destination bits are 
combined. It defaults to boole-1, that is, the source bits are copied unchanged into 
the destination. 

The returned value is the pixmap. 

See the section "Pixmaps in CLIM". 



climrcopy-textual-output-history window stream &optional region record Function 

Given a window window that supports output recording, this function finds all of 
the textual output records that overlap the region region (or all of the textual out- 
put records is region is not supplied), and outputs that text to stream. This can be 
used when you want to capture all of the text on a window into a disk file for 
later perusal. 



clim:copy-to-pixmap medium medium-x medium-y width height &optional pixmap 
(pixmap-x 0) (pixmap-y 0) (op boole-lj Function 

Copies the pixels from the medium medium starting at the position specified by 
(medium-x,medium-y) into the pixmap pixmap at the position specified by (pixmap- 
x,pixmap-y). A rectangle whose width and height is specified by width and height is 
copied, medium-x and medium-y are specified in user coordinates. (If medium is a 
sheet or a stream, then medium-x and medium-y are transformed by the user 
transformation.) 

If pixmap is not supplied, a new pixmap will be allocated. Otherwise, pixmap must 
be an object returned by climrallocate-pixmap that has the appropriate character- 
istics for medium. 

op is a boolean operation that controls how the source and destination bits are 
combined. It defaults to boole-1, that is, the source bits are copied unchanged into 
the destination. 

The returned value is the pixmap. 

See the section "Pixmaps in CLIM". 



climrcursor Class 
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The protocol class that corresponds to a text cursor. If you want to create a new 
class that obeys the cursor protocol, it must be a subclass of climrcursor. 



climrcursor-active cursor Generic Function 

An active cursor is one that is being actively maintained by its owning sheet. 
climrcursor-active returns t if the cursor is active. 

You can use setf on this to change the "active" attribute of the cursor. 



climrcursor-focus cursor Generic Function 

Returns the "focus" attribute of the cursor. When this returns t, the sheet owning 
the cursor has the input focus. 

You can use setf on this to change the "focus" attribute of the cursor. 



climrcursor-position cursor Generic Function 

Returns the cursor position of cursor as two values (X and Y), relative to the up- 
per left corner of the sheet with which the cursor is associated. 

See the section "Manipulating the Cursor in CLIM". 



clim:cursor-set-position cursor x y Generic Function 

Sets the cursor position of cursor to x and y, which are relative to the upper left 
corner of the sheet with which the cursor is associated. 

See the section "Manipulating the Cursor in CLIM". 



climrcursor-sheet cursor Generic Function 

Returns the sheet with which cursor is associated. 

climrcursor-state cursor Generic Function 

Returns t if the cursor is active and visible on its associated sheet. 
You can use setf on this to change the visibility of the cursor. 

climrcursor-visibility cursor Generic Function 

This is a convenience function that combines the functionality of both climrcursor- 
active and climrcursor-state. The visibility can be either ron (meaning that the 
cursor is both active and visible at its current position), roff (meaning that the 
cursor is active, but not visible), or nil (meaning that the cursor is not active). 

You can use setf on this to change the visibility of the cursor. 
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climrcursorp object Generic Function 

Returns t if and only if object is of type climrcursor, otherwise returns nil. 

climrdeactivate-gadget gadget Generic Function 

Causes the gadget to become inactive, that is, unavailable for input. In some envi- 
ronments this may cause the gadget to become grayed over; in others, no visual ef- 
fect may be detected. The function climrnote-gadget-deactivated is called whenev- 
er the gadget is made inactive. 

climrdeallocate-pixmap pixmap Function 

Deallocates the pixmap pixmap. 
See the section "Pixmaps in CLIM". 

clim-sys:deallocate-resource name object &optional allocation-key Function 

Returns the object object to the resource named name, name is a symbol that 
names a resource, object must be an object that was originally allocated from the 
same resource. 

See the section "Resources in CLIM". 

clim:default-describe-presentation-type description stream plural-count Function 

Given a string description that describes a presentation type (such as "integer") 
and plural-count (either nil or an integer), this function pluralizes the string if 
necessary, prepends an indefinite article if appropriate, and outputs the result onto 
stream. 

This function is useful when you are writing your own climrdescribe-presentation- 
type method, but want to get most of CLIM's default behavior. 



clim:default-frame-top-level frame &key .-command-parser xommand-unparser :par- 
tial-command-parser (.-prompt "Command: ") Function 

The default top-level function for application frames. This function enables the 
frame (by calling climrenable-frame), and then enters a "read-eval-print" loop 
that calls climrread-frame-command, then calls climrexecute-frame-command, 

and finally redisplays all of the panes that need to be redisplayed. 

clim:default-frame-top-level establishes a simple restart for conditionsrabort, so 
that anything that invokes an conditionsrabort restart will by default throw to the 
top level command loop of the application frame. (Of course, the programmer can 
specify a restart-case for the conditionsrabort restart.) 

climrdefault-frame-top-level binds several of Lisp's standard stream variables. 
*standard-output* is bound to the value returned by climrframe-standard-output. 
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*standard-input* is bound to the value returned by clim:frame-standard-input. 
*query-io* is bound to the value returned by clim:frame-query-io. 

.■prompt controls the prompt. You can supply either a string or a function of two 
arguments (stream and frame) that outputs the prompt on the stream. The default 
for .-prompt is the string "Command: ". 

To set your own prompt string supply rprompt to the :top-level option of 
clim:define-application-frame: 

(cl im:def ine-appl ication-f rame different-prompt () 
(...) 
( : top-level (cl im: default- frame- top- level 

: prompt "What next, mate? ")) 

If you want the prompt to change as a function of the state of the application, you 
can supply a function (instead of a string): 

(defun promptfun (stream frame) 
(with-slots (prompt-state) frame 

(format stream "Prompt ~D: " prompt-state))) 

(cl im:def ine-appl ication-f rame different-prompts () 
((prompt-state ...) ...) 
( : top-level (cl im: default- frame- top- level 

: prompt promptfun)) 
...) 

The frame's top level loop binds clim:*command-parser*, clim:*command- 
unparser*, and clim:*partial-command-parser* to the values of .-command-parser, 
xommand-unparser, and :partial-command-parser. 

If there is an interactor pane in the frame, : command-parser defaults to 

clim:command-line-command-parser, xommand-unparser defaults to 

clim:command-line-command-unparser, and :partial-command-parser defaults to 
clim:command-line-read-remaining-arguments-for-partial-command. 

If there is no interactor pane, -.command-parser defaults to climrmenu-command- 
parser and -.partial-command-parser defaults to clim:menu-read-remaining- 
arguments-for-partial-command; there is no need for an unparser when there is 
no interactor. 

See the section "Examples of CLIM Application Frames". 



clim:*default-text-style* Variable 

This is the "default default" text style used by all mediums and streams. That is, 
unless a default text style can be computed another way (such as by querying the 
display server), CLIM uses clim:*default-text-style* as the default text style for 
mediums and streams. 
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When doing any kind of text output, if the text style is not fully specified, it is 
merged against the medium's default text style using clim:merge-text-styles. 
Therefore, if you change the value of climr*default-text-style*, the new value 
must be a fully specified text style. 



clim:define-application-frame name superclasses slots &rest options Macro 

Defines an application frame. You can specify a name for the application class, the 
superclasses (if any), the slots of the application class, and options. 

For an overview of how to define CLIM application frames, see the section "Defin- 
ing CLIM Application Frames". 

clim:define-application-frame defines a class with the following characteristics: 

• inherits some behavior and slots from the class climrstandard- 
application-frame, 

• inherits other behavior and slots from any other superclasses which you 
specify explicitly, and 

• has other slots, as explicitly specified by slots. 
None of the arguments is evaluated. The arguments are: 

name A symbol naming the new frame and class. 

superclasses 

A list of superclasses from which the new class should inherit, as in 
closrdefclass. When superclasses is nil, it behaves as though a su- 
perclass of clim:standard-application-frame was supplied. If you do 
specify superclasses to inherit from, you must arrange to inherit 
from clim:standard-application-frame explicitly. 

slots A list of slot specifiers, as in closrdefclass. Each instance of the 

frame will have slots as specified by these slot specifiers. These 
slots will typically hold any per-instance frame state. 

options You can use the CLOS rdefault-initargs option to customize the ini- 
tial values of slots in either your specified superclasses, or in the 
application frame. The following options are also supported: 

rpanes pane-descriptions 

Specifies the application's panes. There is no default for this 
option. The syntax of pane-descriptions is given below. 

rpane form 

Another way of specifying the application's panes. There is no 
default for this option, form is a Lisp form that creates the 
panes of the frame. You may only provide one of rpane or 
rpanes. 
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rlayouts layout 

Specifies the layout of the panes. The default layout is to lay 
the panes out in a vertical stack. The syntax of layout is 
given below. 

:top-level top-level 

Allows you to specify the main loop for your application. By 
default, the top level loop is clim:default-frame-top-level 
(which is adequate for most applications). 

Note: if you use a function other than clim:default-frame- 
top-level as the top level function, you should be sure that it 
calls clim:enable-frame. 

top-level is a list whose first element is the name of a func- 
tion to be called to execute the top level loop. The function 
should take at least one required argument, the frame. The 
rest of the list consists of additional keyword arguments to be 
passed to the function. The default function is climrdefault- 
frame-top-level. (You can use the rprompt keyword of 
clim:default-frame-top-level to control application frame 
prompts in the interactor.) 

If you supply your own function, it must be prepared to re- 
ceive the keyword arguments rcommand-parser, rcommand- 
unparser, rpartial-command-parser, and rprompt. 

rcommand-table name-and-options 

Allows you to specify a particular command table for the ap- 
plication. 

name-and-options is a list consisting of the name of the ap- 
plication's command table followed by some keyword-value 
pairs. The keywords can be :inherit-from or rmenu (which 
are as the same as in climrdefine-command-table). The de- 
fault is to create a command table with the same name as 
the application. 

rcommand-definer value 

When value is nil, no command-defining macro is defined. 
When it is t, a command-defining macro is defined, whose 
name is of the form define-na/ne-command. When it is anoth- 
er symbol, the symbol names the command-defining macro. 
The default is t. 

:menu-bar value 

When value is t (the default), the frame will automatically be 
provided with a menu bar. The exact format of the menu bar 
varies from one window system to another. When value is nil, 
the frame will not have or use the menu bar. value can also 
name a command table; in this case, the commands to put in 
the menu bar are gotten from the named command table. 
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: disabled-commands commands 

Allows you to specify a particular set of initially disabled com- 
mands for the application. The default is nil. 

rdefault-initargs alist 

Provides a set of default initargs for the application frame. 
This is the same as it is for closrdefclass. 

Syntax of the :panes option 

The rpanes option keyword is followed by one or more pane-descriptions. Each 
pane-description can be one of two possible formats: 

• A list consisting of a pane-name (which is a symbol), a pane-type, and pane- 
options, which are keyword-value pairs, pane-options is evaluated at load time. 

• A list consisting of a pane-name (which is a symbol), followed by an expression 
that is evaluated to create the pane. See the macro clim:make-clim-stream- 
pane. See the function clim:make-pane. 

The pane-types are: 

: application 

Application panes are stream panes used for the display of applica- 
tion-generated output. See the class clim:application-pane. See the 
macro clim:make-clim-application-pane. 

rinteractor 

Interactor panes are stream panes that provide a place for the user 
to do interactive input and output. See the class climrinteractor- 
pane. See the macro clim:make-clim-interactor-pane. 

: accept- values 

These panes provide for the display of a "modeless" 
climraccepting-values dialog. See the class 

clim:accept-values-pane. See the section "Using an : accept- values 
Pane in a CLIM Application Frame". 

rpointer-documentation 

These panes provide for pointer documentation. If such a pane is 
specified, then when the pointer moves over different areas of the 
frame, this pane displays documentation of the effect of clicking the 
pointer buttons. 

If the host window system has its own way of displaying pointer 
documentation, this pane may be omitted automatically from the 
layout. 

See the class clim:pointer-documentation-pane. 

:command-menu 

Command menu panes are used to hold a menu of application com- 
mands. The default display function is clim:display-command-menu 
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which, by default, displays the current command table of the frame. 
You can display a different command table by supplying the 
:command-table argument to clim:display-command-menu. 

Many host window systems provide a menu bar, so having panes of 
type :command-menu is not common. 

See the class clim:command-menu-pane. 

rtitle Title panes are used for displaying the title of the application. The 

default title is a "prettied up" version of the name of the applica- 
tion frame's class. 

Many host window systems will automatically display the frame's ti- 
tle in a title bar, so this is only rarely useful. 

See the class clim:title-pane. 

In addition to pane-types, pane-options may be specified as keyword/value pairs. 
Most pane-options can be used by all pane types (exceptions are noted as appro- 
priate). The defaults for the options often vary from one pane type to another. 

rwidth, rheight, :min-width, :min-height, :max-width, and :max-height 

Provide space requirement specs that specify the sized of the pane. 
The values the space requirements can take are described in "Using 
the :LAYOUTS Option to CLIM:DEFINE-APPLICATION-FRAME". 

rbackground and rforeground ink 

Provide initial values for climrmedium-foreground and 
climrmedium-background for the pane. 

:text-style text-style 

Specifies a text style to use in the pane. The default depends on the 
pane type. 

rborders Controls whether borders are drawn around CLIM stream panes (t 
or nil). The default is t. The value may also be a list, in which case 
the value is used as options to climroutlining. 

rspacing Controls whether there is some whitespace between the border and 
the viewport for a CLIM stream pane (t or nil). The default is t. 
The value may also be a list, in which case the value is used as op- 
tions to climrspacing. 

:scroll-bars scroll-bar-spec 

A scroll-bar-spec can be :both (the default for : application panes), 
rhorizontal, rvertical, :none, or nil. The pane will have only those 
scroll bars which were specified. :none means that the pane will 
support scrolling, but does not have any visible scroll bars, nil 
means that the pane will not support scrolling at all. 

:display-after-commands 

One of t, nil, or :no-clear. If t, the "print" part of the read-eval- 
print loop runs the display function; this is the default for most 
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pane types. If nil, you are responsible for managing the display af- 
ter commands. 

:no-clear behaves the same as t, with the following change. If you 
have not specified rincremental-redisplay t, then the pane is nor- 
mally cleared before the display function is called. However, if you 
specify :display-after-commands :no-clear, then the pane is not 
cleared before the display function is called. 

: display-function display-spec 

Where display-spec is either the name of a function or a list whose 
first element is the name of a function. The function is to be ap- 
plied to the application frame, the pane, and the rest of display-spec 
if it was a list when the pane is to be redisplayed. 

The function must accept two required arguments (the frame and 
the pane), plus the two keyword arguments :max- width and :max- 
height. 

One example of a predefined display function is climrdisplay- 
command-menu. 

rdisplay-string string 

(for rtitle panes only) The string to display. The default is the 
frame's pretty name. 

rlabel string 

A string to be used as a label for the pane, or nil (the default). 

rincremental-redisplay boolean 

If t, CLIM runs the display function inside of an climrupdating- 
output form. The default is nil. 

:end-of-line-action, :end-of -page-action 

Initial values of the corresponding attributes. See the macro 
clim:with-end-of-line-action and see the macro clim:with-end-of- 
page-action. 

rinitial-cursor-visibility 

:off means make the text cursor visible if the window is waiting for 
input. :on means make it visible all the time, nil means that the 
cursor is never visible. The default is :off for rinteractor and 
: accept- values panes, and nil for other panes. 

routput-record 

Specify this if you want a different output history mechanism than 
the default (which is clim:standard-tree-output-history). For ex- 
ample, a graphic editing program might supply a value of: 

(make- instance 'cl im: r- tree-output-history) 

Besides clim:standard-tree-output-history and clim:r-tree-output- 
history, you can also use climrstandard-sequence-output-history. 
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:draw-p, :record-p boolean 

Specifies the initial state of drawing and output recording. 

: default- view view 

Specifies the view object to use for the stream's default view. 

:text-margin integer 

Text margin to use if clim:stream-text-margin isn't set. This de- 
faults to the width of the viewport. 

rvertical-spacing integer 

Amount of extra space between text lines. 

rpointer-cursor 

Specifies the pointer cursor to use when the pointer is over this 
pane. 

:event-queue 

Specifies the event queue to be used by this pane. The default is to 
share the event queue with the top-level sheet, so that all the panes 
in the frame use the same event queue. 

Syntax of the :layouts option 

Here is a brief description of the syntax of the rlayouts option: 
rlayouts (layout-name layout-panes) 

layout-name is a symbol. 

layout-panes is layout-panesl or (size-spec layout-panesl). 

layout-panesl is a pane-name, or a lay out-macro- form, or layout-code. 

layout-code is Lisp code that generates a pane, which may 
include the name of a named pane. 

size-spec is a positive real number less than 1, or :fill, or 
rcompute. A real number (between zero and one, exclusive) is 
the fraction of the available space to use. :fill means that the 
pane will take as much space as remains when all its sibling panes 
have been given space, rcompute means that the pane's display 
function should be called in order to compute how much space it 
requires. (Note that the display function is run at frame-creation 
time, so it must be able to compute the size correctly at that time.) 

size-spec can also be an integer indicating the size of the pane 
in device units, or a list whose first element is a real number 
and whose second element is a "unit" (one of rline, 
rcharacter, :mm, rpoint, or rpixel). 
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layout-macro-form is {layout-macro-name {options) &rest layout-panes). 

layout-macro-name is climrvertically, climrhorizontally, 
climrtabling, climroutlining, climrspacing, or 
climrlabelling. 



For a detailed explanation of the rlayouts option see the section "Using the LAY- 
OUTS Option to CLIM:DEFINE-APPLICATION-FRAME". 
See the section "Examples of CLIM Application Frames". 

clim:define-border-type shape arglist &body body Macro 

Defines a new kind of border named shape for use by climrsurrounding-output- 

with-border. arglist will typically be (stream record left top right bottom). 

body is the code that actually draws the border. It has lexical access to stream, 
record, left, top, right, and bottom, which are respectively, the stream being 
drawn on, the output record being surrounded, and the coordinates of the left, top, 
right, and bottom edges of the bounding rectangle of the record. 

After the border has been drawn, clim:surrounding-output-with-border positions 
the text cursor at the end of the bordered output. Since the size of a border may 
vary greatly, CLIM needs a hint as to where the text cursor should be placed rela- 
tive to the bordered output. If the returned value of body is a small real number, 
it is used as the hint that controls the Y offset of the final text cursor. 

The predefined border types, rrectangle, :oval, :drop-shadow, and runderline are 

defined using this macro. Here is how the rectangular border type is defined: 

(def ine-border-type : rectangle 

(stream left top right bottom 

&rest drawing-options &key (filled nil) &al low-other-keys) 
(declare (dynamic-extent drawing-options)) 
(let ((offset 2)) 

(apply #'draw-rectanglex stream 

(- left offset) (- top offset) 
(+ right offset) (+ bottom offset) 
:filled filled drawing-options)) 
;; Y offset for text cursor is 3 
3) 



climrdefine-command name arguments &body body Macro 

Defines a command and its characteristics, including its name, its arguments, and 
optionally the command table in which it should appear, its keystroke accelerator, 
its command-line name, and whether or not (and how) to add this command to the 
menu associated with the command table. For example, the follow defines a com- 
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mand that has a command-line name, appears in a command menu, and has a 
keystroke accelerator. 

(cl im:def ine-command (com-my- favorite-command 

:name "my fave" 
: keystroke #\F 
:menu "favorite" 

: command-table my-command-table) 
((argl '(or integer string) 
:default "none" 
: display-default t)) 
body) 

climrdefine-command is the most basic command-defining form. Usually, the pro- 
grammer will not use climrdefine-command directly, but will instead use a de- 
fine-application-command form that is automatically generated by climrdefine- 
application-frame. define-appZicafton-command adds the command to the appli- 
cation's command table. By default, climrdefine-command does not add the com- 
mand to any command table. 

climrdefine-command defines two functions. The first function has the same name 
as the command name, and implements the body of the command. It takes as argu- 
ments the arguments to the command as specified in the climrdefine-command 
form, as required and keyword arguments. 

The second function defined by climrdefine-command is used internally by CLIM 
and implements the code responsible for parsing and returning the command's ar- 
guments. 

name Either a command name, or a cons of the command name and a list 
of keyword-value pairs. The keyword-value pairs in name can be: 

rcommand-table command-table-name 

Specifies that the command should be added to a command 
table, command-table-name either names a command table to 
which the command should be added, or is nil (the default) to 
indicate that the command should not be added to any com- 
mand table. This keyword is only accepted by climrdefine- 
command, not by define-appZicafton-command functions. 

mame string 

Provides a name to be used as the command-line name for 
the command for keyboard interactions in the command table 
specified by the rcommand-table option, string is a string to 
be used; or nil (the default) meaning that the command will 
not be available via command-line interactions; or t, which 
means the command-line name will be generated automatical- 
ly. See the function climradd-command-to-command-table. 

rmenu menu-item 

Specifies that this command will be an item in the menu of 
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the command table specified by the :command-table option. 
The default is nil, meaning that the command will not be 
available via menu interactions. If menu-item is a string, then 
that string will be used as the menu name. If menu-item is t, 
then the menu name will be generated automatically. See the 
function clim:add-command-to-command-table. Otherwise, 
menu-item is a cons of the form (string . menu-options), where 
string is the menu name and menu-options consists of key- 
word-value pairs. The valid keywords are rafter and 
: documentation, which are interpreted as for climradd-menu- 
item-to-command-table. 

rkeystroke gesture-spec 

Specifies a gesture to be used as a keystroke accelerator in 
the command table specified by the :command-table option. 
For applications with interactor panes, these gesture should 
correspond to non-printing characters such as #\control-D 
(whose gesture spec is (:D : control)). The default is nil, 
meaning that there is no keystroke accelerator. 

The :name, rmenu, and rkeystroke options are allowed only if the 
rcommand-table option was supplied explicitly or implicitly, as in 
define-appZicafton-command. 

If the command takes any non-keyword arguments and you have 
supplied either menu or rkeystroke, then when you select this 
command via a command menu or keystroke accelerator, a partial 
command parser will be invoked in order to read the unsupplied ar- 
guments; the defaults will not be filled in automatically. If this be- 
havior is not desired, then you must call climradd-menu-item-to- 
command-table or climradd-keystroke-to-command-table yourself 
and fully specify the command. For example, use the following in- 
stead of supplying rkeystroke for the com-next-frame command: 

(def ine-debugger-command (com-next-frame :name t) 
((nframes 'integer 
: default 1 

:prompt "number of frames")) 
(next-frame : nframes nframes)) 

(cl im : add-keystroke-to-command-tabl e 

'debugger '(:n : control) : command '(com-next-frame 1)) 

arguments 

A list consisting of argument descriptions. A single occurrence of 
the symbol &key may appear in arguments to separate required 
command arguments from keyword arguments. Each argument de- 
scription consists of a list containing a parameter variable, followed 
by a presentation type specifier, followed by keyword-value pairs. 
The keywords can be: 
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: default value 

Provides a value which is the default that should be used for 
the argument, as for climraccept. 

: default-type type 

The same as for climraccept. If rdefault is supplied, then the 
rdefault and the :default-type are returned if the input is 
empty. 

rmentioned-default value 

Provides a value which is the default that should be used for 
the argument when a keyword is explicitly supplied via the 
command-line processor, but no value is supplied for it. 
rmentioned-default is allowed only for keyword arguments. 
This is most often used for boolean keyword arguments in 
conjunction with rdefault 

(delete-after-printer 'boolean 
:default nil :mentioned-defaul t t 
: prompt "yes or no") 

rdisplay-default boolean 

The same as for climraccept. When true, displays the default 
if one was supplied. When nil, the default is not displayed. 

rprompt string 

Provides a string which is a prompt to print out during com- 
mand-line parsing, as for climraccept. 

r documentation string 

Provides a documentation string that describes what the ar- 
gument is. When you type Help when entering keyword argu- 
ments, this documentation will be displayed. 

rwhen form 

Provides a form that indicates whether this keyword argu- 
ment is available. The form is evaluated in a scope where the 
parameter variables for the required parameters are bound, 
and if the result is nil, the keyword argument is not avail- 
able, rwhen is allowed only on keyword arguments, and form 
cannot use the values of other keyword arguments. 

rgesture pointer-gesture-name 

Provides a gesture name that will be used for a translator 
that translates from the argument to a command, rgesture is 
allowed only when the rcommand-table option was supplied 
to the command-defining form. The default is that no transla- 
tor will be created. Explicitly supplying rgesture nil creates a 
translator that will appear only in the translator menus. 

pointer-gesture-name can also be a list whose car is a pointer 
gesture name, and whose cdr is a list of translator options 
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that may include rtester, menu, rpriority, :echo, 
: documentation, and rpointer-documentation. 

body Provides the body of the command. It has lexical access to all of the 

command's arguments. If the body of the command needs access to 
the application frame, it should use clim:*application-frame*. The 
returned values of body are ignored. 

climrdefine-command arranges for the function that implements the body of the 
command to get the proper values for unsupplied keyword arguments. 

name-and-options and body are not evaluated. In the argument descriptions, the pa- 
rameter variable name is not evaluated, and everything else is evaluated at run- 
time when argument parsing reaches that argument, except that the value for 
:when is evaluated when parsing reaches the keyword arguments, and rgesture is 
not evaluated at all. 

See the section "Commands in CLIM". 



clim:define-command-table name &key :inherit-from :menu :inherit-menu Macro 

Defines a command table whose name is the symbol name. The keyword arguments 
are: 

dnherit-from 

A list of either command tables or command table names. The new 
command table inherits from all of the command tables specified by 
dnherit-from. The inheritance is done by union with shadowing. In 
addition to inheriting from the explicitly specified command tables, 
every command table defined with clim:define-command-table also 
inherits from CLIM's system command table. (This command table, 
clim:global-command-table, contains such things as the "menu" 
translator that is associated with the right-hand button on pointers.) 

-.menu Specifies a menu for the command table. The value of :menu is a 
list of clauses. Each clause is a list with the syntax (string type val- 
ue &key documentation keystroke), where string, type, value, docu- 
mentation, and keystroke are as for clim:add-menu-item-to- 
command-table. 

dnherit-menu 

Normally, a menu does not inherit any menu items or keystroke ac- 
celerators from its parents. When dnherit-menu is t, the menu items 
and keystroke accelerators will be inherited. When it is :menu, only 
the menu items will be inherited. When it is rkeystrokes, only the 
keystroke accelerators will be inherited. 

If the command table named by name already exists, clim:define-command-table 
will modify the existing command table to have the new value for dnherit-from and 
-.menu, but will otherwise leave the other attributes for the existing table alone. 
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None of the arguments to clim:define-command-table arguments is evaluated. 
See the section "CLIM Command Tables". 



climrdefine-default-presentation-method presentation-function-name [qualifiers]* 
specialized-lambda-list &body body Macro 

This is like climrdefine-presentation-method, except that it is used to define a de- 
fault method that will be used if there are no more specific methods. 



None of the arguments is evaluated. 



clim:define-drag-and-drop-translator name (from-type to-type destination-type com- 
mand-table &key (.-gesture 'rselectj .-tester .-documentation (.-menu t) .-priority .-feed- 
back .-highlighting .-pointer-cursor) arglist &body body Macro 

Defines a "drag and drop" (or "direct manipulation") translator named name that 
translates from objects of type from-type to objects of type to-type when a "from 
presentation" is "picked up", "dragged" over, and "dropped" on a "to presenta- 
tion" having type destination-type, from-type, to-type, and destination-type are pre- 
sentation type specifiers, but must not include any presentation type options, from- 
type, to-type and destination-type may be presentation type abbreviations. See the 
section "Presentation Translators in CLIM". 

The interaction style used by these translators is that a user points to a "from 
presentation" with the pointer, picks it up by pressing a pointer button matching 
.-gesture, drags the "from presentation" to a "to presentation" by moving the 
pointer, and then drops the "from presentation" onto the "to presentation". The 
dropping might be accomplished by either releasing the pointer button or clicking 
again, depending on the frame manager. When the pointer button is released, the 
translator whose destination-type matches the presentation type of the "to presen- 
tation" is chosen. For example, dragging a file to the TrashCan on a Macintosh 
could be implemented by a drag and drop translator. 

While the pointer is being dragged, the function specified by .-feedback is invoked 
to provide feedback to the user. The function is called with eight arguments: the 
application frame object, the "from presentation", the stream, the initial X and Y 
positions of the pointer, the current X and Y positions of the pointer, and a feed- 
back state (either rhighlight to draw feedback, or runhighlight to erase it). The 
feedback function is called to draw some feedback the first time pointer moves, 
and is then called twice each time the pointer moves thereafter (once to erase the 
previous feedback, and then to draw the new feedback). It is called a final time to 
erase the last feedback when the pointer button is released, -.feedback defaults to 
clim:frame-drag-and-drop-feedback, whose default method simply draws the 
bounding rectangle of the object being dragged. 

When the "from presentation" is dragged over any other presentation that has an 
applicable direct manipulation translator, the function specified by .-highlighting is 
invoked to highlight that object. The function is called with four arguments: the 
application frame object, the "to presentation" to be highlighted or unhighlighted, 
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the stream, and a highlighting state (either rhighlight or runhighlight). .-highlight- 
ing defaults to clim:frame-drag-and-drop-highlighting, whose default method sim- 
ply draws a box around the object over which the dragged object may be dropped. 

The other arguments to clim:define-drag-and-drop-translator are the same as for 
climrdefine-presentation-translator. See the macro climrdefine-presentation- 
translator. 

It is possible for there to be more than one drag and drop translator that applies 
to the same from type, to type, destination type, and gesture. In this case, the ex- 
act translator that is chosen for use during the dragging phase is unpredictable. If 
these translators have different feedback, highlighting, documentation, or pointer 
documentation, the feedback and highlighting behavior is unpredictable. 

For example, suppose you are implementing some sort of desktop interface to a file 
system editor that has commands such as "Hardcopy File", "Delete File", and so 
forth, and you want a drag-and-drop interface. Assuming you have some icons that 
represent a hardcopy device, a trashcan, and so forth, and presentation types that 
correspond to those icons, you could do the following: 

(cl i m : def i ne-drag-and-drop-transl ator dm-hardcopy-f i 1 e 
(pathname command printer fsedit-comtab 

: documentation "Hardcopy this file") 
(object destination-object) 
1 (com-hardcopy-f ile , object , destination-object)) 

(cl i m : def i ne-drag-and-drop-transl ator dm-del ete-f i 1 e 
(pathname command trashcan fsedit-comtab 

: documentation "Delete this file") 
(object) 
1 (com-delete-f ile , object)) 

(cl i m : def i ne-drag-and-drop-transl ator dm-copy-f i 1 e 
(pathname command folder fsedit-comtab 

: documentation "Copy this file") 
(object destination-object) 
1 (com-copy-f ile , object 

, (make-pathname :name (pathname-name object) 
type (pathname-type object) 
defaults destination-object))) 



climrdefine-genera-application frame-name &rest keys &key :pretty-name .select-key 
deft stop .-right .-bottom .-width .-height Macro 

Makes a CLIM application available to the Select Activity command and optional- 
ly to the SELECT key. frame-name is the symbol used as the name argument to 
clim:define-application-frame. 

Note: climrdefine-genera-application exists only under Genera. Therefore, you 
should put #+Genera in front of any calls to it. 
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frame-name 

A symbol which is the name argument to climrdefine-application- 
frame. 

:pretty-name 

A string which is the name used as a title and as the activity 
name. It defaults to a prettified version of frame-name. 

.select-key A character to be used with the SELECT key. It defaults to nil which 
means that no SELECT character is assigned. 

deft, stop, .-right, .-bottom 

The coordinates of the frame, deft and stop default to 0, and .-right 
and .-bottom default to nil. 

.-height, .-width 

The size of the frame, .-height and .-width default to clim:+fill+, 
meaning the frame will fill the entire screen. 

None of the arguments is evaluated. 



clim:define-gesture-name name type gesture-spec &key (.-unique t) Macro 

Defines a gesture named name by calling clim:add-gesture-name. 

For more information, see clim:add-gesture-name. 

None of the arguments is evaluated. 

CLIM's standard pointer gestures on a platform with a 3-button mouse (such as 
Genera) could be defined with the following forms: 



(cl im:def ine-gestu re-name 
(cl im:def ine-gestu re-name 
(cl im:def ine-gestu re-name 
(cl im:def ine-gestu re-name 
(cl im:def ine-gestu re-name 
(cl im:def ine-gestu re-name 



select 

describe 

menu 

delete 

edit 

modify 



pointer (:left)) 

pointer (: middle)) 

pointer (:right)) 

pointer (:middle : shift)) 

pointer (:left :meta)) 

pointer (:right :control :meta)) 



climrdefine-presentation-action name (from-type to-type command-table &key (.-ges- 
ture 'rselect) .-tester .-documentation .-pointer-documentation (-menu t) .-priority) arglist 
&body body Macro 

This is similar to climrdefine-presentation-translator, except that the body of the 
action is not intended to return a value, but should instead side-effect some sort of 
application state. A typical presentation action might scroll a window in an appli- 
cation, or select another translator from a menu. 



name The name of the presentation action. 

from-type The presentation type of the presentation on a window. Presentation 
type options are not allowed in from-type. 
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to-type The presentation type of the current input context. Presentation 
type options are not allowed in to-type. When to-type is nil, this ac- 
tion is applicable in all input contexts. 

command-table 

This specifies which command table the translators should be stored 
in. It should be either a command table or the name of a command 
table. This translator will be applicable only when this command ta- 
ble is one of the command tables from which the current applica- 
tion frame's command table inherits. 

The other arguments to climrdefine-presentation-action are the same as for 
climrdefine-presentation-translator. For information on the arguments, see the 
macro climrdefine-presentation-translator. 

None of the arguments to climrdefine-presentation-action is evaluated. 

Note that an action does not satisfy requests for input as translators do. An ordi- 
nary translator satisfies a request for input, but an action is something that hap- 
pens while waiting for input. After executing an action, the program continues to 
wait for the same input it was waiting for prior to executing the action. 

In general, if you are using climrdefine-presentation-action to execute any kind of 
an application command, you should be using climrdefine-presentation-translator 
or clim:define-presentation-to-command-translator instead. 

From time to time, it is appropriate to write application-specific presentation ac- 
tions. The key test for whether something should be an action is that it makes 
sense for the action to take place while the user is entering a command sentence 
and performing the action will not interfere with the input of the command sen- 
tence. For example, an application framework might have an action that changes 
what information is displayed in one of its panes. It makes sense to do this in the 
middle of entering a command because information displayed in that pane might 
be used in formulating the arguments to the command. This needn't interfere with 
the input of the command since a pane can be redisplayed without discarding the 
pending partial command. It is for these cases that the presentation action mecha- 
nism is provided. A simple rule of thumb is that actions may be used to alter how 
application objects are presented or displayed, but anything having to do with mod- 
ification of application objects should be embodied in a command, with an appropri- 
ate set of translators. 



climrdefine-presentation-generic-function generic-function-name presentation- 
function-name lambda-list &rest options Macro 

Defines a new presentation named presentation-function-name whose methods are 
named by generic- function-name, lambda-list and options are as for closrdefgeneric. 

The first few arguments in lambda-list are treated specially. The first argument 
must be either type-key or type-class. If you wish to be able to access type pa- 
rameters or options in the method, the next arguments must be either or both of 
parameters and options. Finally, a required argument called type must also be 
included in lambda-list. 
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Most user programs will never need to define their own presentation type generic 
function. CLIM uses it internally. For example, clim:describe-presentation-type 
might be have been defined by the following: 

(cl im:def ine-presen tat ion-generic- function 
descri be-presentati on- type-method cl i m : descri be-presentati on- type 
(type-key parameters options type stream plural -count)) 

None of the arguments is evaluated. 



climrdefine-presentation-method presentation-function-name [qualifiers]* special- 
ized-lambda-list &body body Macro 

Defines a presentation method for the function named presentation-function-name 
on the presentation type named in specialized-lambda-list. The value of presenta- 
tion-function-name can be any of the presentation generic functions defined by 
CLIM (climraccept, climrpresent, clim:describe-presentation-type, 

clim:presentation-typep, climrpresentation-subtypep, 

climraccept-present-default, clim:presentation-type-specifier-p, 

clim:presentation-refined-position-test, or climrhighlight-presentation) or any 
presentation generic function you have defined yourself. 

specialized-lambda-list is a CLOS specialized lambda list for the method, and its 
contents varies depending on what presentation-function-name is. qualifier* is zero 
or more of the usual CLOS method qualifiers, body defines the body of the method. 

None of the arguments is evaluated. 

For example, the following might be used to implement the climraccept and 
climrpresent methods for the null type: 

(cl im:def ine-presen tat ion-method cl im: present 

(object (type null) stream (view cl im: textual-view) &key) 
(declare (ignore object)) 
(write-string "None" stream)) 

(cl im:def ine-presen tat ion-method cl im: accept 

((type null) stream (view cl im: textual-view) &key) 
(let ((token (cl im: read-token stream))) 
(unless (string-equal token "None") 

(cl im: input-not-of-requi red-type token type)) 
nil)) 

For more information about presentation methods, see the section "Presentation 
Methods in CLIM". 



climrdefine-presentation-to-command-translator name (from-type command-name 
command-table &key (.-gesture 'rselect) .-tester .-documentation .-pointer-documentation 
(.-menu t) .-priority (-.echo t)) arglist &body body Macro 
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Defines a presentation translator that translates a displayed presentation into a 
command. 

This is similar to climrdefine-presentation-translator, except that the to-type will 
be derived to be the command named by command-name in the command table 
command-table, command-name is the name of the command that this translator 
will translate to. See the section "Presentation Translators in CLIM". 

The :echo argument controls whether or not the command should be echoed in the 
command line when a user invokes this translator. The default for :echo is t. 

The other arguments to clim:define-presentation-to-command-translator are the 
same as for climrdefine-presentation-translator. For information on the argu- 
ments, see the macro climrdefine-presentation-translator. 

The body of the translator should return a list of the arguments to the command 
named by command-name, body is run in the context of the application. The re- 
turned value of the body, appended to the command name, is eventually passed to 
clim:execute-frame-command. 

For example, the following translators can be found in the CLIM Lisp Listener: 

(cl im:def ine-presen tat ion-to-command- translator show-file-translator 
(pathname com-show-f ile lisp-listener 
: gesture : select 

:pointer-documentation "Show File") 
(object) 
(1 ist object)) 

(cl im:def ine-presen tat ion-to-command- translator edit-f ile- translator 
(pathname com-edit-f ile lisp-listener 
:gesture :edit 

:pointer-documentation "Edit File") 
(object) 
(1 ist object)) 

None of the arguments to clim:define-presentation-to-command-translator is 
evaluated. 



climrdefine-presentation-translator name (from-type to-type command-table &key 
(.-gesture 'rselectj .-tester .-tester-definitive .-documentation .-pointer-documentation 
(.-menu t) .-priority) arglist &body body Macro 

Defines a presentation translator named name which translates from objects of 
type from-type to objects of type to-type. From-type and to-type are presentation type 
specifiers, but must not include presentation type options. From-type and to-type 
may also be presentation type abbreviations, to-type can also be nil , in which case 
the translator applies in any input context since nil is a subtype of all presentation 
types. See the section "Presentation Translators in CLIM". 

None of the arguments to climrdefine-presentation-translator is evaluated. The 
arguments are described as follows: 
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name The name of the presentation translator. 

from-type The presentation type of the presentation on a window. Presentation 
type options are not allowed in from-type. When from-type is t, this 
translator is applicable to all presentation types. 

to-type The presentation type of the returned object. Presentation type op- 
tions are not allowed in to-type. When to-type is nil, this translator 
is applicable in all input contexts. 

command-table 

This specifies which command table the translators should be stored 
in. It should be either a command table or the name of a command 
table. This translator will be applicable only when this command ta- 
ble is one of the command tables from which the current applica- 
tion frame's command table inherits. 

.■gesture A gesture-name (see the section "Gestures and Gesture Names in 
CLIM"). The body of the translator will be run only if the translator 
is applicable and the pointer event corresponding to the user's ges- 
ture matches the gesture name in the translator. For more infor- 
mation, see the section "Applicability of CLIM Presentation Transla- 
tors", -.gesture defaults to rselect. 

rgesture t means that any user gestures will match this translator, 
and rgesture nil, means that no user gesture will match this trans- 
lator, rgesture nil is commonly used when the translator should ap- 
pear only in a menu. 

.■tester Either a function or a list of the form (tester-arglist . tester-body), 
where tester-arglist takes the same form as arglist (see below), and 
tester-body is the body of the tester. The tester should return either 
t or nil. If it returns nil, then the translator is definitely not appli- 
cable. If it returns t, then the translator might be applicable, and 
the body of the translator may be run in order to definitively decide 
if the translator is applicable (for more information, see the section 
"Applicability of CLIM Presentation Translators"). If no tester is 
supplied, CLIM arranges for a tester that always returns t. 

Use this when you want to restrict the cases when a translator will 
be applicable. 

.■tester-definitive 

When this is t and the tester returns t, this translator is definitely 
applicable. When this is nil and the tester returns t, this translator 
might be applicable; in order to find out for sure, the body of the 
translator is run, and, if it returns an object that matches the input 
context type (using climrpresentation-typep), this translator is ap- 
plicable. 

.■documentation 

An object that will be used to document the translator. For exam- 
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pie, in menus: if the object is a string, the string itself will be used 
as the documentation. Otherwise, it should be either a function or a 
list of the form (doc-arglist . doc-body), where doc-arglist takes the 
same form as arglist, but includes a stream argument as well (see 
below), and doc-body is the body of the documentation function. The 
body of the documentation function should write the documentation 
to stream. The default is nil, meaning that there is no documenta- 
tion. 

.■pointer-documentation 

Like the : documentation option except that .-pointer-documentation 
is used in the pointer documentation line. This documentation is 
usually more succinct than normal documentation. If .-pointer- 
documentation is not supplied, it defaults to .-documentation. 

.-menu 

The value should be t or nil. The default is t, meaning the transla- 
tor is to be included in the menu popped-up by the menu gesture 
(click Right on a three-button mouse). Use menu t rgesture nil to 
make the translator accessible only through the menu. :menu nil 
means that the translator should not appear in the menu. 

.-priority A non-negative integer that represents the priority of the translator. 
The default is 0. When there are several translators that match for 
the same gesture, the one with the highest priority is chosen. 

The priority is broken into a "high order" part and a "low order" 
part. The high order part of the priority is the "tens" place (base 
10), and the low order part is the "ones" place. 

You can create an "overriding" translator that always precedes any 
other applicable translators by supplying a high order priority 
greater than the high order priority of other translators. You can 
"break ties" between translators that translate from the same type 
by supplying a low order priority greater than the low order priority 
of other translators. Since the high order priority always overrides 
all other applicable translators, you should be careful about supply- 
ing priorities that have a high order part. 

arglist, tester-arglist, doc-arglist 

An argument list that must be a subset (using string-equal to com- 
pare symbol names) of the "canonical" argument list: 

{object presentation context-type frame event window x y) 

In the body of the translator (or the tester), object will be bound to 
the presentation's object, presentation will be bound to the presenta- 
tion that was clicked on, context-type will be bound to the presenta- 
tion type of the context that actually matched, frame will be bound 
to the application frame that is currently active (usually 
clim:*application-frame*), event will be bound to the object repre- 
senting the gesture that the user used, window will be bound to the 
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window stream from which the event came, and x and y will be 
bound to the X and Y positions within window where the pointer 
was when the user issued the gesture. The special variable 
climr*input-context* will be bound to the current input context. 

body The body of the translator, and may return one, two, or three val- 

ues. The first returned value is an object that must be 
clim:presentation-typep of to-type. The second value is either nil or 
a presentation type that must be climrpresentation-subtypep of to- 
type. 

The third returned value is either nil or a list of options (as key- 
word-value pairs) that will be interpreted by climraccept. The only 
option currently used by climraccept is recho. If :echo is t (the de- 
fault), the object returned by the translator will be "echoed" by in- 
serting its textual representing into the input buffer. If :echo is nil, 
the object will not be echoed. 

body is run in the context of the application. The first two values 
returned by body are used, in effect, as the returned values for the 
call to climraccept that established the matching input context. 



climrdefine-presentation-type name parameters &key .-options :inherit-from .-descrip- 
tion .-history :parameters-are-types Macro 

Defines a CLIM presentation type. See the section "Defining a New Presentation 
Type in CLIM". 

name The name of the presentation type, name is a symbol or a class ob- 
ject. 

parameters 

Parameters of the presentation type. These parameters are lexically 
visible within the rinherit-from form and within the methods creat- 
ed with climrdefine-presentation-method. For example, the parame- 
ters are used by climrpresentation-typep to refine its tests for type 
inclusion. 

.-options A list of option specifiers, which defaults to nil. An option specifier 
is either a symbol or a list (symbol &optional default supplied-p pre- 
sentation-type accept-options) . The elements symbol, default, and sup- 
plied-p are as in a normal lambda-list. If presentation-type and ac- 
cept-options are present, they specify how to accept a new value for 
this option from the user, symbol can also be specified in the (key- 
word variable) form allowed for Common Lisp lambda lists, symbol 
is a variable that is visible within the rinherit-from form and with- 
in most of the methods created with climrdefine-presentation- 
method. The keyword corresponding to symbol can be used as an 
option in the third form of a presentation type specifier. An option 
specifier for the standard option rdescription is automatically added 
to .-options if an option with that keyword is not present. 
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:inherit-from 

A form that evaluates to a presentation type specifier for another 
type from which the new type inherits. :inherit-from can access the 
parameter variables bound by the parameters lambda list and the 
option variables specified by options. If name is or names a CLOS 
class, then dnherit-from must specify the class's direct superclasses 
(using and to specify multiple inheritance). It is useful to do this 
when you want to parameterize previously defined CLOS classes. 

If dnherit-from is unsupplied, it defaults as follows: If name is or 
names a CLOS class, then the type inherits from the presentation 
type corresponding to the direct superclasses of that CLOS class 
(using and to specify multiple inheritance). Otherwise, the type in- 
herits from closrstandard-object. 

Note: you cannot use clim:define-presentation-type to create a new 
subclass any of the built-in types, such as integer or symbol. 

■.history Specifies what history to use for the presentation type. 

nil (the default) Uses no history. 

t Uses its own history. 

type-name Uses type-name's history. 

If you want more flexibility, you can define a climrpresentation- 
type-history presentation method. 

■.description 

A string or nil. If nil or unsupplied, a description is automatically 
generated; it will be a "prettied up" version of the type name. For 
example, small-integer would become "small integer". You can also 
write a clim:describe-presentation-type presentation method. 

Unsupplied optional or keyword parameters default to * (as they do in deftype) if 
no default is specified in parameters. Unsupplied options default to nil if no default 
is specified in -.options. 

There are certain restrictions on the :inherit-from form, to allow it to be analyzed 
at compile time. The form must be a simple substitution of parameters and options 
into positions in a fixed framework. It cannot involve conditionals or computations 
that depend on valid values for the parameters or options; for example, it cannot 
require parameter values to be numbers. It cannot depend on the dynamic or lexi- 
cal environment. The form will be evaluated at compile time with uninterned sym- 
bols used as dummy values for the parameters and options. In the type-specifier 
produced by evaluating the form, the type name must be a constant that names a 
type, the type parameters cannot derive from options of the type being defined, 
and the type options cannot derive from parameters of the type being defined. All 
presentation types mentioned must be already defined, and can be used for multi- 
ple inheritance, but or, not, and satisfies cannot be used. 
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clim:define-presentation-type-abbreviation name parameters expansion &key .-op- 
tions Macro 

Defines a presentation type that is an abbreviation for the presentation type speci- 
fier that is the value of expansion. Note that you cannot define any presentation 
methods on a presentation type abbreviation. If you need to define methods, use 
clim:define-presentation-type instead. 

name must be a symbol and must not be the name of a CLOS class, parameters 
and .-options are the same as they are for clim:define-presentation-type. 

The type-specifier produced by evaluating expansion can be a real presentation 
type or another abbreviation. 

This example defines a presentation type to read an octal integer: 

(cl im:def ine-presen tat ion- type-abb rev i at ion octal -integer 

(&optional low high) 
'((integer ,low ,high) :base 8 : description "octal integer")) 



clim-sys:defresource name parameters &key .-constructor .-initializer ideinitializer 
-.matcher -.initial-copies Macro 

Defines a resource named name; name must be a symbol, parameters is a lambda- 
list giving names and default values (for optional and keyword parameters) of pa- 
rameters to an object of this type. 

.-constructor is a form that is responsible for creating an object, and is called when 
someone tries to allocate an object from the resource and no suitable free objects 
exist. The constructor form can access the parameters as variables. This argument 
is required. 

.-initializer is a form that is used to initialize an object gotten from the resource. It 
can access the parameters as variables, and also has access to a variable called 
name, which is the object to be initialized. The initializer is called both on newly 
created objects and objects that are being reused. 

ideinitializer is a form that is used to deinitialize an object when it is about to be 
returned to the resource. It can access the parameters as variables, and also has 
access to a variable called name, which is the object to be deinitialized. It is 
called whenever an object is deallocated back to the resource, but is not called by 
clim-sys:clear-resource. Deinitializers are typically used to clear references to oth- 
er objects. 

-.matcher is a form that ensures that an object in the resource "matches" the spec- 
ified parameters, which it can access as variables. In addition, the matcher also 
has access to a variable called name, which is the object in the resource being 
matched against. If no matcher is supplied, the system remembers the values of 
the parameters (including optional ones that defaulted) that were used to construct 
the object, and assumes that it matches those particular values for all time. This 
comparison is done with equal. The matcher should return t if there is a match, 
otherwise it should return nil. 
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.■initial-copies is used to specify the number of objects that should be initially put 
into the resource. It must be an integer or nil (which is the default), meaning that 
no initial copies should be made. If initial copies are made and there are parame- 
ters, all the parameters must be optional; in this case, the initial copies have the 
default values of the parameters. 

The following example defines a resource of strings that can be used to avoid con- 
stantly allocating and garbage collecting strings: 

(cl im-sys:def resource temporary-string 

(&key (length 100) (adjustable t)) 
: constructor 

(make-array length 

: element-type 'character 
: f il 1-pointer 
: adjustable adjustable) 
:matcher 

(and (eq adjustable (adjustable-array-p temporary-string)) 
(or (and (not adjustable) 

(= length (array-dimension temporary-string 0))) 
(<= length (array-dimension temporary-string 0)))) 
initializer (setf (fill-pointer temporary-string) 0)) 

(defmacro with-temporary-string 

((var &key (length 100) (adjustable t)) &body body) 
1 (cl im-sys:using-resource (,var temporary-string 

: length , length adjustable , adjustable) 
,@body)) 

See the section "Resources in CLIM". 



clim:delete-gesture-name gesture-name Function 

Removes the gesture named gesture-name. 

climrdelete-output-record child record &optional errorp Generic Function 

Removes the child output record child from the output record record. If child is 
not contained in record and errorp is t, an error is signalled. 

Any class that is a subclass of climroutput-record must implement this method. 

See the section "Concepts of CLIM Output Recording". 

clim:delimiter-gesture-p gesture Function 

Returns t if gesture is a currently active delimiter gesture. 

clim:*delimiter-gestures* Variable 
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A list containing the gesture names of the currently active delimiter gestures. 



clim:describe-presentation-type presentation-type &optional (stream *standard- 
output*) (plural-count I) Function 

Describes the presentation-type on the stream. 

If stream is nil, a string containing the description is returned, plural-count is ei- 
ther nil (meaning that the description should be the singular form of the name), t 
(meaning that the description should the plural form of the name), or an integer 
greater than zero (the number of items to be described). 

The presentation-type can be a presentation type abbreviation. 



clim:describe-presentation-type type-key parameters options type stream plural- 
count Clim Presentation Method 

This presentation method is responsible for textually describing the type type, 
stream will be a stream of some sort, never nil. plural-count is as for the 
clim:describe-presentation-type function. 

For example, CLIM's complex number is described with the following methods. It 
is written as an rafter method because CLIM provides a default method that does 
most of the work. 

(cl im:def ine-presen tat ion-method cl im:describe-presen tat ion- type : after 

((type complex) stream plural -count) 
(declare (ignore type plural -count)) 
(unless (eq type '*) 

(format stream " whose components are ") 

(cl im:describe-presentation-type type stream t))) 



climrdesign Class 

A design is an object that represents a way of arranging colors and opacities in 
the drawing plane, climrdesign is a generalization of climrregion to include color. 



climrdestroy-frame frame Generic Function 

Disables the application frame frame, and then destroys it by deallocating all of its 
CLIM resources and disowning it from its frame manager. After the frame has 
been destroyed, its state will be rdisowned. 



climrdestroy-port port Generic Function 

Destroys the connection to the display server represented by port. All of the appli- 
cation frames, frame managers, and sheets associated with port will be destroyed. 
All server resources used by the frames and sheets (such as graphics contexts) are 
released as part of the shutdown. 
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clim-sys:destroy-process process Function 

Terminates the process process, process is a process object, such as is returned by 
clim-sys:make-process. 



clim:device-event Class 

The superclass of all other CLIM device events. This is a subclass of climrevent. 

clim-sys:disable-process process Function 

Disables the process process, that is, prevents it from becoming runnable until it is 
enabled again. 

climrdisarmed-callback gadget client id Generic Function 

This callback is invoked when the gadget gadget is disarmed. The exact definition 
of disarming varies from gadget to gadget, but typically a gadget becomes dis- 
armed when the pointer is moved out of its region. 

The default method for climrdisarmed-callback (on climrbasic-gadget) calls the 
function specified by the rdisarmed-callback initarg. 



clim:display-command-menu frame stream &key : command-table :max-width :max- 
height :n-rows :n-columns (:cell-align-x 'rleftj (:cell-align-y 'rtopj Function 

Displays the menu described by the command table associated with the application 
frame frame onto stream. This is generally used as the display function for applica- 
tion panes of type :command-menu. 

.■command-table is the command table to display; it defaults to frame's current com- 
mand table. The following options are used to control the appearance of the com- 
mand menu. 

:max-width 

Specifies the maximum width, in device units, of the table display. 

:max-height 

Specifies the maximum height, in device units, of the table display. 

:n-rows 

Specifies the number of rows of the table. Specifying this overrides 
:max-width. 

:n-columns 

Specifies the number of columns of the table. Specifying this over- 
rides :max-height. 

:cell-align-x 

Specifies the horizontal placement of each of the cells in the com- 
mand menu. This is like the :align-x option to clim:formatting-cell. 
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:cell-align-y 

Specifies the horizontal placement of each of the cells in the com- 
mand menu. This is like the :align-y option to clim:formatting-cell. 

clim:display-command-menu displays the disabled command menu items as well 
as the enabled ones, but the disabled items will be "grayed out". 



clim:display-command-table-menu command-table stream &key :max-width :max- 
height :n-rows :n-columns :x-spacing .y-spacing (:cell-align-x 'rleftj (:cell-align-y ':top) 
(.■initial-spacing t) :row-wise :move-cursor Function 

Displays the menu for command-table on stream. The following options are used to 
control the appearance of the command menu. 

:max-width 

Specifies the maximum width, in device units, of the table display. 

:max-height 

Specifies the maximum height, in device units, of the table display. 

:n-rows 

Specifies the number of rows of the table. Specifying this overrides 
:max-width. 

:n-columns 

Specifies the number of columns of the table. Specifying this over- 
rides :max-height. 

:x-spacing 

Determines the amount of space inserted between columns of the 
table; the default is the width of a space character. :x-spacing can 
be specified in one of the following ways: 

Integer 

A size in the current units to be used for spacing. 

String or character 

The spacing is the width or height of the string or char- 
acter in the current text style. 

Function 

The spacing is the amount of horizontal or vertical space 
the function would consume when called on the stream. 

List of form (number unit) 

The unit is rpoint, rpixel, or rcharacter. 

.y-spacing 

Specifies the amount of blank space inserted between rows of the 
table; the default is the vertical spacing for the stream. The possi- 
ble values for this option are the same as for the :x-spacing option. 
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:cell-align-x 

Specifies the horizontal placement of each of the cells in the com- 
mand menu. This is like the :align-x option to clim:formatting-cell. 

:cell-align-y 

Specifies the horizontal placement of each of the cells in the com- 
mand menu. This is like the :align-y option to clim:formatting-cell. 

.■initial-spacing 

When doing the layout, CLIM tries to evenly space items across the 
entire width of the stream. When this option is t, no whitespace is 
inserted before the first item on a line. 

:row-wise When this is nil, if there are multiple columns in the item list, the 
entries in the item list are arranged in a manner similar to entries 
in a phone book. Otherwise the entries are arranged in a "row- 
wise" fashion. The default is t. 

■.move-cursor 

When t (the default), CLIM moves the text cursor to the end (lower 
right corner) of the output. Otherwise, the cursor is left at the be- 
ginning (upper left corner) of the output. 



clim:display-exit-boxes frame stream view Generic Function 

Displays the exit boxes for the climraccepting-values frame frame on the stream 
stream using the view view. The exit boxes specification is not passed in directly, 
but is a slot in the frame. 

CLIM has default methods that either writes a line of text associating the Exit 
and Abort strings with presentations that either exit or abort from the dialog (in 
the textual view), or create push buttons that contain the Exit and Abort strings. 

You can create your own subclass of the climraccepting-values frame class, and 
then specialize clim:display-exit-boxes for you own kind of exit boxes. In this case, 
you will need to provide the rframe-class option to climraccepting-values. It is 
often sufficient to simply provide the rexit-boxes option to climraccepting-values. 



climrdisplayed-output-record Class 

The protocol class that is used to indicate that an object is a displayed output 
record, that is, a CLIM object that represents a visible piece of output on an out- 
put device. If you want to create a new class the obeys the displayed output record 
protocol, it must be a subclass of climrdisplayed-output-record. 

If you think of output records being arranged in a tree, displayed output records 
are the leaves of the tree. Displayed text and graphics are examples of things that 
are displayed output records. 

See the section "Output Recording in CLIM". 
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clim:displayed-output-record-p object Function 

Returns t if and only object is of type climrdisplayed-output-record. 



clim:do-command-table-inheritance (command-table-var command-table) &body 
body Macro 

Successively evaluates body with command-table-var bound first to the command ta- 
ble command-table, and then to all of the command tables from which command- 
table inherits. The recursion follows a depth-first path, considering the "inheri- 
tees" of the first inheritee before considering the second inheritee. This is the 
precedence order for command table inheritance. 

climrdocument-presentation-translator translator presentation context-type frame 
event window x y &key (.stream *standard-output*) .-documentation-type Function 

Computes the documentation string for translator, and displays it on the stream 
.stream, presentation, context-type, frame, gesture, window, x, and y are as for 
climrfind-applicable-translators. 

.■documentation-type should be either rnormal or rpointer. When it is rnormal, the 
translator should generate "normal" documentation. Otherwise it should generate 
the pointer documentation, which is usually shorter. 



climrdolist-noting-progress (var listform name &optional stream note-var) &body 
body Function 

Binds the dynamic environment such that the progress of a dolist special form is 
noted by a progress bar displayed in the specified stream (usually the pointer doc- 
umentation pane). 

var is a variable bound to each successive element in listform on each successive 
iteration, listform is the list, name is a string naming the operation being noted; 
this string is displayed with the progress bar. 

note-var is a variable bound to the current note object; the default is 
clim: *current-progress-note* . 

(defun note-element-printing (list) 

(cl im:dol ist-noting-progress (element list "Printing elements") 
(print element) 
(sleep 1))) 



climrdotimes-noting-progress (var countform name &optional stream note-var) 
&body body Macro 

Binds the dynamic environment such that the progress of a dotimes special form 
is noted by a progress bar displayed in the specified stream (usually the pointer 
documentation pane). 
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var is a variable bound to the count (0, 1, 2, and so on) on each successive itera- 
tion, countform is the number of iterations, name is a string naming the operation 
being noted; this string is displayed with the progress bar. 

note-var is a variable bound to the current note object; the default is 
clim: *current-progress-note* . 

(defun note-square-roots (n) 
(cl i m : dot imes-noting-pr ogress 

(count n "Calculating square roots") 
(sqrt count) ;whoopee! 
(sleep 1))) 



climrdrag-callback gadget client id value Generic Function 

This callback is invoked when the value of a slider or scroll bar is changed while 
the indicator is being dragged. This is implemented by calling the function speci- 
fied by the :drag-callback initarg with two arguments, the slider (or scroll bar) 
and the new value. Generally, this function will call another programmer-specified 
callback function. 



climrdrag-output-record stream output-record &key (.-repaint t) .-multiple-window 
.-erase .-feedback (:finish-on-release t) Function 

Enters an interaction mode in which user moves the pointer, and output-record fol- 
lows the pointer by being dragged on stream. 

.-repaint Allows you to specify the appearance of windows as the pointer is 
dragged. If .-repaint is t (the default), displayed contents of windows 
are not disturbed as output-record is dragged over them (that is, 
those regions of the screen are repainted). 

.-erase Allows you to identify a function to erase the output record (the de- 
fault effectively uses climrerase-output-record). .-erase is a function 
of two arguments, the output record to erase, and the stream. 

.-feedback Allows you to identify a feedback function, .-feedback is a function of 
seven arguments: the output record, the stream, the initial X and Y 
position of the pointer, the current X and Y position of the pointer, 
and a drawing argument (either rerase, or :draw). 

Use .-feedback if you want more complex feedback than is supplied 
by default, for instance, if you want to draw a "rubber band" line 
as the user moves the mouse. The default for .-feedback is nil. 

.-multiple-window 

When t, specifies that the pointer is to be tracked across multiple 
windows. The default is nil. 
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:finish-on-release 

When this is t (the default), the body is exited when the user re- 
leases the mouse button currently being held down. When this is 
nil, the body is exited when the user clicks a mouse button. 

Note that if .-feedback is supplied, -.erase is ignored. 



climrdragging-output f&optional stream &key (-.repaint t) .-multiple-window -.finish- 
on-release) &body body Macro 

Evaluates body to produce the output, and then invokes climrdrag-output-record 
to drag that output on stream, stream defaults to *standard-input*. 

.-repaint allows you to control the appearance of windows as the pointer is dragged. 
If .-repaint is t (the default), displayed contents of windows are not disturbed as 
output-record is dragged over them (that is, those regions of the screen are re- 
painted). 

.-multiple-window is as for climrdrag-output-record. 

If :finish-on-release is t (the default), climrdragging-output is exited when the 
user releases the mouse button currently being held down. When it is nil, 
climrdragging-output is exited when the user clicks a mouse button. 



climrdraw-arrow medium start-point end-point &key :from-head (:to-head t) (.-head- 
length 10) (-.head-width 5) .-line-style :line-thickness -.line-unit :line-dashes :line-cap- 
shape :ink -.clipping-region -.transformation Function 

Draws an arrow on medium. The arrow starts at the position specified by start- 
point and ends with the arrowhead at the position specified by end-point, two point 
objects. 

This function is the same as climrdraw-arrow*, except that the positions are spec- 
ified by points, not by X and Y positions. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-arrow* medium xl yl x2 y2 &key :from-head (:to-head t) (-head-length 
10) (:head-width 5) .-line-style :line-thickness -.line-unit :line-dashes :line-cap-shape 
-.ink -.clipping-region -.transformation Function 

Draws an arrow on medium. The arrow starts at the position specified by (xl,yl) 
and ends with the arrowhead at the position specified by (x2,y2). 
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For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-circle medium center radius &key .start-angle :end-angle (.-filled t) :line- 
style :line-thickness :line-unit :line-dashes :line-cap-shape sink .-clipping-region .-trans- 
formation Function 

Draws a circle or arc on medium. The center of the circle is specified by the point 
center, and the radius is specified by radius. 

This function is the same as climrdraw-circle*, except that the center position is 
expressed as a point instead of X and Y positions. See the function climrdraw- 
circle*. 

.start-angle and -.end-angle 

Enable you to draw an arc rather than a complete circle in the 
same manner as that of the ellipse functions. See the function 
climrdraw-ellipse*. 

The defaults for -.start-angle and -.end-angle are nil (that is, a full 
circle). 

-.filled Specifies whether the circle should be filled, a boolean value. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-circle* medium center-x center-y radius &key -.start-angle -.end-angle 
(-.filled t) -.line-style :line-thickness -.line-unit :line-dashes :line-cap-shape sink .-clip- 
ping-region .-transformation Function 

Draws a circle or arc on medium. The center of the circle is specified by center-x 
and center-y, and the radius is specified by radius. 

.start-angle and -.end-angle 

Enable you to draw an arc rather than a complete circle in the 
same manner as that of the ellipse functions. See the function 
climrdraw-ellipse*. 
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The defaults for .start-angle and :end-angle are nil (that is, a full 
circle). 

:filled Specifies whether the circle should be filled, a boolean value. 

Both climrdraw-circle* and climrdraw-circle call climrmedium-draw-ellipse* to do 

the actual drawing. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-design design stream &key :ink : clipping-region .-transformation :line-style 
■.unit .-thickness -.joint-shape xap-shape .-dashes .-text-style .-text-family -.text-face -.text- 
size Generic Function 

Draws design on stream. The additional keyword arguments are used in a manner 
that depends upon the type of the design. For example, for designs that are paths 
(such as lines and unfilled circles), you may include the :line-style keyword. 

The design types are: 

area Paints the specified region of the drawing plane with stream's 

current ink. 

path Strokes the path with stream's current ink under control of the 

line-style. 

point The same as clim:draw-point. 

a color or an opacity 

Paints the entire drawing plane (subject to the medium's clip- 
ping region). 

clim:+nowhere+ 

This has no effect. 

If design is a non-uniform design this paints the design positioned at coordinates 
(x=0, y=0). 

climrdraw-design is currently supported for the following designs: 

• Designs created by the geometric object constructors (such as 
clim:make-line and climrmake-ellipse). 

• Designs created by clim:compose-in, where the first argument is an 
ink and the second argument is a design. 

• clim:compose-over of designs created by clim:compose-in. 
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• Designs returned by clim:make-design-from-output-record. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-ellipse medium point radius-1-dx radius-1-dy radius-2-dx radius-2-dy 
&key .start-angle :end-angle (.-filled t) -.line-style :line-thickness :line-unit :line-dashes 
:line-cap-shape sink .-clipping-region .-transformation Function 

Draws an ellipse or elliptical arc on medium. The center of the ellipse is specified 
by point. 

This function is the same as climrdraw-ellipse*, except that the center position is 
expressed as a point instead of X and Y. See the function climrdraw-ellipse*. 

Two vectors, radius-1-dx, radius-1-dy, and radius-2-dx, radius-2-dy specify the 
bounding parallelogram of the ellipse. Those two vectors must not be collinear in 
order for the ellipse to be well defined. The special case of an ellipse with its ma- 
jor axes aligned with the coordinate axes can be obtained by setting both radius-1- 
dy and radius-2-dx to 0. For more information about the bounding parallelogram of 
an ellipse, see the section "Ellipses and Elliptical Arcs in CLIM". 

.start-angle and -.end-angle 

Enable you to draw an arc rather than a complete ellipse. Angles 
are measured with respect to the positive X-axis. The elliptical arc 
runs positively from -.start-angle to :end-angle. The angles are mea- 
sured from the positive X-axis toward the positive Y-axis. In a right- 
handed coordinate system this direction is counter-clockwise. 

The defaults for -.start-angle and -.end-angle are nil (that is, a full 
ellipse). If you supply -.start-angle, then -.end-angle defaults to 2pi. If 
you supply :end-angle, then .start-angle defaults to 0. 

.-filled Specifies whether the ellipse should be filled, a boolean value. 

In the case of a filled arc, the figure drawn is the "pie slice" area swept out by a 
line from the center of the ellipse to a point on the boundary as the boundary 
point moves from .start-angle to :end-angle. 

When drawing unfilled ellipses, the current line style affects the drawing as usual, 
except that the joint shape has no effect. The dashing of an elliptical arc starts at 
.start-angle. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 
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For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-ellipse* medium center-x center-y radius-1-dx radius-1-dy radius-2-dx ra- 
dius-2-dy &key .start-angle :end-angle (.-filled t) -.line-style :line-thickness :line-unit 
:line-dashes :line-cap-shape sink .-clipping-region .-transformation Function 

Draws an ellipse or elliptical arc on medium. The center of the ellipse is specified 
by center-x and center-y. 

This function is the same as climrdraw-ellipse, except that the center position is 
expressed as its X and Y coordinates, instead of as a point. See the function 
climrdraw-ellipse. 

Both climrdraw-ellipse* and climrdraw-ellipse call climrmedium-draw-ellipse* to 

do the actual drawing. 

Two vectors, radius-1-dx, radius-1-dy, and radius-2-dx, radius-2-dy specify the 
bounding parallelogram of the ellipse. Those two vectors must not be collinear in 
order for the ellipse to be well defined. The special case of an ellipse with its ma- 
jor axes aligned with the coordinate axes can be obtained by setting both radius-1- 
dy and radius-2-dx to 0. For more information about the bounding parallelogram of 
an ellipse, see the section "Ellipses and Elliptical Arcs in CLIM". 

.start-angle and -.end-angle 

Enable you to draw an arc rather than a complete ellipse. Angles 
are measured with respect to the positive X-axis. The elliptical arc 
runs positively from -.start-angle to :end-angle. The angles are mea- 
sured from the positive X-axis toward the positive Y-axis. In a right- 
handed coordinate system this direction is counter-clockwise. 

The defaults for -.start-angle and -.end-angle are nil (that is, a full 
ellipse). If you supply -.start-angle, then -.end-angle defaults to 2pi. If 
you supply :end-angle, then .start-angle defaults to 0. 

.-filled Specifies whether the ellipse should be filled, a boolean value. 

In the case of a filled arc, the figure drawn is the "pie slice" area swept out by a 
line from the center of the ellipse to a point on the boundary as the boundary 
point moves from .start-angle to :end-angle. 

When drawing unfilled ellipses, the current line style affects the drawing as usual, 
except that the joint shape has no effect. The dashing of an elliptical arc starts at 
.start-angle. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 
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For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



clim:draw-line medium point-1 point-2 &key -.line-style :line-thickness :line-unit :line- 
dashes :line-cap-shape sink :clipping-region .-transformation Function 

Draws a line segment on medium. The line starts at the position specified by 
point-1 and ends at the position specified by point-2, two point objects. 

This function is the same as clim:draw-line*, except that the positions are speci- 
fied by points, not by X and Y positions. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



clim:draw-line* medium xl yl x2 y2 &key -.line-style :line-thickness -.line-unit -.line- 
dashes :line-cap-shape sink .-clipping-region .-transformation Function 

Draws a line segment on medium. The line starts at the position specified by (xl, 
yl), and ends at the position specified by (x2, y2). 

Both clim:draw-line* and clim:draw-line call clim:medium-draw-line* to do the 

actual drawing. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



clim:draw-lines medium point-seq &key -.line-style :line-thickness -.line-unit -.line- 
dashes :line-cap-shape sink .-clipping-region .-transformation Function 

Draws a set of disconnected line segments onto medium, point-seq is a sequence of 
pairs of points. Each point pair specifies the starting and ending point of one line. 

This function is semantically equivalent to calling clim:draw-line repeatedly, but it 
can be more convenient and efficient when drawing more than one line segment. 
See the function clim:draw-line. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 
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For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



clim:draw-lines* medium coord-seq &key -.line-style :line-thickness :line-unit :line- 
dashes :line-cap-shape sink :clipping-region .-transformation Function 

Draws a set of disconnected line segments onto medium, coord-seq is a sequence of 
pairs of X and Y positions. Each pair of pairs specifies the starting and ending 
point of one line. 

This function is equivalent to calling clim:draw-line* repeatedly, but it can be 
more convenient and efficient when drawing more than one line segment. See the 
function clim:draw-line*. 

Both clim:draw-lines* and clim:draw-lines call clim:medium-draw-lines* to do 

the actual drawing. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



clim:draw-oval medium point x-radius y-radius &key (.-filled t) .-line-style .-line- 
thickness -.line-unit :line-dashes :line-cap-shape sink .-clipping-region .-transformation 

Function 

Draws an oval, that is, a "race-track" shape, centered on point, a point object. If 
x-radius or y-radius is 0, draws a circle with the specified non-zero radius; other- 
wise, draws the figure that results from drawing a rectangle with dimensions x-ra- 
dius and y-radius and then replacing the two short sides with semicircular arc of 
appropriate size. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



clim:draw-oval* medium center-x center-y x-radius y-radius &key (.-filled t) .-line- 
style :line-thickness -.line-unit :line-dashes :line-cap-shape sink .-clipping-region .-trans- 
formation Function 
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Draws an oval, that is, a "race-track" shape, centered on (center-x center-y): if x-ra- 
dius or y-radius is 0, draws a circle with the specified non-zero radius; otherwise, 
draws the figure that results from drawing a rectangle with dimensions x-radius 
and y-radius and then replacing the two short sides with semicircular arc of appro- 
priate size. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-pattern* stream pattern x y &key : clipping-region transformation 

Function 

Draws the pattern pattern on stream at the position (x,y). pattern is a design creat- 
ed by calling climrmake-pattern, for example, 

(dim: make-pattern #2A((0 0011000 



(0 
(0 1 
(1 1 
(1 1 
(0 1 
(0 
(0 



1 1 
1 1 



1 1 
1 1 
1 1 



1 
1 1 
1 1 
1 



(list cl im:+background-ink+ 
cl im:+foreg round- ink+)) 

You could also make the above pattern translucent by using climr+transparent- 
ink+ instead of clim:+background-ink+. In that case, the output underneath the 
pattern will show through wherever there is a zero value in the pattern. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-pixmap medium pixmap point &rest args &key sink .-clipping-region 
.■transformation (.-function boole-lj Function 

Draws the pixmap pixmap on medium at the position point. This function is the 
same as climrdraw-pixmap*, except that the position is specified by a point object, 
not by an X/Y position. 
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.■function is a boolean operation that controls how the source and destination bits 
are combined. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-pixmap* medium pixmap x y &rest args &key sink .-clipping-region 
.■transformation (.-function boole-lj Function 

Draws the pixmap pixmap on medium at the position (x,y). pixmap is a pixmap cre- 
ated by using clim:copy-area or clim:with-output-to-pixmap. Unlike climrcopy- 
area, climrdraw-pixmap* will create a "pixmap output record" when called on an 
output recording stream. 

.■function is a boolean operation that controls how the source and destination bits 
are combined. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-point medium point &key -.line-style :line-thickness :line-unit sink .-clip- 
ping-region .-transformation Function 

Draws a point on medium at the position indicated by point. 

CLIM uses the medium's line style to decide how to draw a point on a display de- 
vice. The -.line-unit and :line-thickness arguments control the size on the display de- 
vice of the "blob" used to render the point. 

The -.line-unit and :line-thickness arguments control the size on the display device 
of the "blob" used to render the point. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 
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climrdraw-point* medium x y &key -.line-style :line-thickness :line-unit sink .-clip- 
ping-region .-transformation Function 

Draws a point on medium at the position indicated by x and y. 

CLIM uses the medium's line style to decide how to draw a point on a display de- 
vice. The -.line-unit and :line-thickness arguments control the size on the display de- 
vice of the "blob" used to render the point. 

Both climrdraw-point* and clim:draw-point call climrmedium-draw-point* to do 

the actual drawing. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-points medium point-seq &key -.line-style :line-thickness -.line-unit sink 
.-clipping-region .-transformation Function 

Draws a set of points on medium, point-seq is a sequence of point objects specify- 
ing where a point is to be drawn. 

This function is equivalent to calling clim:draw-point repeatedly, but it can be 
more convenient and efficient when drawing more than one point. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-points* medium coord-seq &key -.line-style :line-thickness -.line-unit sink 
.-clipping-region .-transformation Function 

Draws a set of points on medium, coord-seq is a sequence of pairs of X/Y pairs 
(that is, a sequence of alternating X coordinates and Y coordinates which when 
taken pairwise specify the points to be drawn). 

This function is equivalent to calling climrdraw-point* repeatedly, but it can be 
more convenient and efficient when drawing more than one point. 

Both climrdraw-points* and climrdraw-points call climrmedium-draw-points* to 

do the actual drawing. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 
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For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-polygon medium point-seq &key (.-closed t) (.-filled t) .-line-style .-line- 
thickness -.line-unit :line-dashes :line-joint-shape :line-cap-shape sink .-clipping-region 
.-transformation Function 

Draws a polygon, or sequence of connected lines, on medium. The keyword argu- 
ments control whether the polygon is closed (each segment is connected to two 
other segments) and filled, point-seq is a sequence of points that indicate the start 
of a new line segment. 

This function is the same as climrdraw-polygon*, except that the segments are 
specified by points, not X and Y positions. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-polygon* medium coord-seq &key (-closed t) (-filled t) .-line-style .-line- 
thickness -.line-unit :line-dashes :line-joint-shape :line-cap-shape sink .-clipping-region 
.-transformation Function 

Draws a polygon, or sequence of connected lines, on medium. The keyword argu- 
ments control whether the polygon is closed (each segment is connected to two 
other segments) and filled, coord-seq is a sequence of alternating X and Y positions 
that indicate the start of a new line segment. 

.-filled Specifies whether the polygon should be filled, a boolean value. If t, 
a closed polygon is drawn and filled in. In this case, .-closed is as- 
sumed to be t. 

.-closed When t, specifies that a segment is drawn connecting the ending 
point of the last segment to the starting point of the first segment. 

Both climrdraw-polygon* and climrdraw-polygon call climrmedium-draw- 

polygon* to do the actual drawing. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 



Page 1524 



For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-rectangle medium pointl point2 &rest args &key -.line-style .-line- 
thickness :line-unit :line-dashes :line-joint-shape sink .-clipping-region .-transformation 
(.-filled t) Function 

Draws an axis-aligned rectangle on medium. The boundaries of the rectangle are 
specified by the two points pointl and point2. 

This function is the same as climrdraw-rectangle*, except that the positions are 
specified by points, not by X and Y positions. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-rectangle* medium xl yl x2 y2 &key (.-filled t) .-line-style :line-thickness 
-.line-unit :line-dashes :line-joint-shape sink .-clipping-region .-transformation Function 

Draws an axis-aligned rectangle on medium. The boundaries of the rectangle are 
specified by xl, yl, x2, and y2, with (xl,yl) at the upper left and (x2,y2) at the low- 
er right in the standard +Y-downward coordinate system. 

.-filled Specifies whether the rectangle should be filled, a boolean value. If 
t, a closed rectangle is drawn and filled in. 

Both climrdraw-rectangle* and climrdraw-rectangle call climrmedium-draw- 

rectangle* to do the actual drawing. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-rectangles medium point-seq &rest args &key -.line-style :line-thickness 
-.line-unit :line-dashes :line-joint-shape sink .-clipping-region .-transformation (-filled t) 

Function 

Draws a set of axis-aligned rectangles on medium, point-seq is a sequence of pairs 
of points. Each point specifies the upper left and lower right corner of the rectan- 
gle in the standard +Y-downward coordinate system. 
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This function is equivalent to calling climrdraw-rectangle repeatedly, but it can 
be more convenient and efficient when drawing more than one rectangle. See the 
function climrdraw-rectangle. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-rectangles* medium coord-seq &rest args &key : line-style : line-thickness 
:line-unit :line-dashes :line-joint-shape sink .-clipping-region .-transformation (.-filled t) 

Function 

Draws a set of axis-aligned rectangles on medium, coord-seq is a sequence of 4-tu- 
ples xl, yl, x2, and y2, with (xl,yl) at the upper left and (x2,y2) at the lower right 
in the standard +Y-downward coordinate system. 

.-filled Specifies whether the rectangle should be filled, a boolean value. If 
t, a closed rectangle is drawn and filled in. 

This function is equivalent to calling climrdraw-rectangle* repeatedly, but it can 
be more convenient and efficient when drawing more than one rectangle. See the 
function climrdraw-rectangle*. 

Both climrdraw-rectangles* and climrdraw-rectangles call climrmedium-draw- 

rectangles* to do the actual drawing. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-standard-menu menu presentation-type items default-item &key (.-item- 
printer #'climrprint-menu-itemj :max-width :max-height :n-rows :n-columns :x- 
spacing :y-spacing :row-wise (:cell-align-x 'rleftj (:cell-align-y 'rtop) Function 

climrdraw-standard-menu is the function used by CLIM to draw the contents of a 
menu, unless the current frame manager determines that host window toolkit 
should be used to draw the menu instead, menu is the stream onto which to draw 
the menu, and presentation-type is the presentation type to use for the menu items 
(usually climrmenu-item). 

.-item-printer is a function of two arguments used to draw each item. The first ar- 
gument is the menu item, and the second is the stream. 
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The other arguments are as for climrmenu-choose. 



clim:draw-text medium text point &key (.start 0) send (:align-x rleft) (:align-y 
rbaseline,) :towards-point :text-style -.text-family :text-face :text-size sink .-clipping- 
region .-transformation Function 

Draws text onto medium starting at the position specified by point, text can be ei- 
ther a character or a string. 

This function is the same as climrdraw-text*, except that the position is expressed 
as a point instead of as X and Y coordinate values. See the function climrdraw- 
text*. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrdraw-text* medium text x y &key (.start 0) send (:align-x rleft) (:align-y 
rbaseline,) :towards-x :towards-y -.text-style -.text-family -.text-face -.text-size sink .-clip- 
ping-region .-transformation Function 

Draws text onto medium starting at the position specified by x and y. text can be 
either a character or a string. 

The exact definition of "starting at" is dependent on :align-x and :align-y; by de- 
fault, the first glyph is drawn with its left edge and its baseline at the position 
specified by x and y. 

.start and send 

Delimit a substring of text when text is a string, .start defaults to 0, 
and send defaults to the length of text. 

:align-x Specifies the horizontal placement of the text string. Can be one of: 
:left (the default), rright, or reenter. 

rleft means that the left edge of the first character of the string is 
at the specified X coordinate, rright means that the right edge of 
the last character of the string is at the specified X coordinate. 
reenter means that the string is horizontally centered over the spec- 
ified X coordinate. 

:align-y Specifies the vertical placement of the string. Can be one of: 
rbaseline (the default), rtop, rbottom, or reenter. 

rbaseline means that the baseline of the string is placed at the 
specified Y coordinate, rtop means that the top of the string is at 
the specified Y coordinate, rbottom means that the bottom of the 
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string is at the specified Y coordinate, reenter means that the 
string is vertically centered over the specified Y coordinate. 

:towards-x and :towards-y 

Changes the direction of the baseline from one glyph to the next. 
Normally, glyphs are drawn from left to right no matter what 
transformation is in effect. If, however, :towards-x is less than x, 
then glyphs will be drawn from right to left. If :towards-y is less 
than y, then glyphs will be drawn from bottom to top. 

Note that :towards-x and :towards-y are not presently implemented 
on all platforms. 

Note that the medium's transformation does not affect the text size. It only affects 
the starting position (x,y), and the ending position (and hence the orientation of 
the baseline) if :towards-x or :towards-y is supplied. 

Both climrdraw-text* and clim:draw-text call climrmedium-draw-text* to do the 

actual drawing. 

For background information on drawing graphics, see the section "Drawing Graph- 
ics in CLIM", and see the section "Using CLIM Drawing Options". 

For detailed information about CLIM line style suboptions, see the section "CLIM 
Line Style Suboptions". 

For detailed information about CLIM drawing options, see the section "Set of 
CLIM Drawing Options". 



climrellipse Class 

The protocol class that corresponds to a mathematical ellipse. This is a subclass of 
climrarea. If you want to create a new class that obeys the ellipse protocol, it 
must be a subclass of climrellipse. 



climrellipse-center-point ellipse Generic Function 

Returns the center point of ellipse. 

climrellipse-center-point* ellipse Generic Function 

Returns the center point of ellipse as two values representing the coordinate pair. 

climrellipse-end-angle ellipse Generic Function 

Returns the end angle of ellipse. If elliptical-object is a full ellipse or closed path 
then climrellipse-end-angle will return nil; otherwise the value will be a number 
greater than zero, and less than or equal to 2pi. 
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clim:ellipse-radii ellipse Generic Function 

Returns four values corresponding to the two radius vectors of ellipse. These val- 
ues may be canonicalized in some way, and so may not be the same as the values 
passed to the constructor function. 



clim:ellipse-start-angle ellipse Generic Function 

Returns the start angle of ellipse. If elliptical-object is a full ellipse or closed path 
then clim:ellipse-start-angle will return nil; otherwise the value will be a number 
greater than or equal to zero, and less than 2pi. 



climrellipsep object Function 

Returns t if and only if object is of type climrellipse. 

clim:elliptical-arc Class 

The protocol class that corresponds to a mathematical elliptical arc. This is a sub- 
class of climrpath. If you want to create a new class that obeys the elliptical arc 
protocol, it must be a subclass of clim:elliptical-arc. 

clim:elliptical-arc-p object Function 

Returns t if and only if object is of type clim:elliptical-arc. 

clinirenable-frame frame Generic Function 

Enables the application frame frame and changes the state of the frame to 
renabled. This involves creating and laying out the panes of the frame (if they 
have not been created already) and exposing the frame. 

Note: If your application frame has its own top level loop (that is, something other 
than clim:default-frame-top-level), it must call clini:enable-frame in order to en- 
able the frame. 

clim-sys:enable-process process Function 

Allows the process process to become runnable again after it has been disabled. 



clim:erase-input-buffer input-editing-stream &optional start-position 

Generic Function 

Erases the part of the display that corresponds to the input editor's buffer starting 
at the position start-position. 
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For more information on the input editor, see the section "The Structure of the 
CLIM Input Editor". 



climrerase-output-record record stream &optional (errorp t) Function 

Erases the display of the output record record from stream, and removes the record 
from stream's output history. After the record is erased, all of the output records 
that overlapped it are replayed in order to ensure that the appearance of the rest 
of the output on stream is correct. 

If record is not in the stream's output history and errorp is t, CLIM will signal an 
error. 

If record is a list of output records rather than a single output record, the replay 
operation will be delayed until after all of the output records have been removed 
from the output history. Passing a list of output records to climrerase-output- 
record can be substantially faster than calling climrerase-output-record multiple 
times. 



climreven-scaling-transformation-p transform Generic Function 

Returns t if transform multiplies all X-lengths and Y-lengths by the same magni- 
tude, otherwise returns nil. This includes pure reflections through vertical and 
horizontal lines. 



climrevent Class 

The class that corresponds to any kind of CLIM event. This includes device events 
(such as keyboard and pointer events), window manager events, and timer events. 



climrevent-matches-gesture-name-p event gesture-name &optional port Function 

Returns t if the device event event "matches" the gesture named by gesture-name. 

For pointer button events, the event matches the gesture name when the pointer 
button from the event matches the name of the pointer button one of the gesture 
specifications named by gesture-name, and the modifier key state from the event 
matches the names of the modifier keys in that same gesture specification. 

For keyboard events, the event matches the gesture name when the key name 
from the event matches the key name of one of the gesture specifications named 
by gesture-name, and the modifier key state from the event matches the names of 
the modifier keys in that same gesture specification. 

climrevent-modifier-state event Generic Function 

Returns the state of the keyboard's shift keys when the event event occurred. The 
returned value is an integer with 1 bits that correspond to the shift keys that were 
being held down. 
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Key Mask 

rshift clim:+shift-key+ 

rcontrol clim:+control-key+ 

:meta clim:+meta-key+ 

rsuper clim:+super-key+ 

rhyper clim:+hyper-key+ 



clim:event-sheet event Generic Function 

Returns the window on which the device event event occurred. 

clim:event-type event Generic Function 

For the event event, returns a keyword symbol with the same name as the class 
name, except stripped of the "-event" ending. For example, when you call 
clim:event-type on an object who class is clim:key-press-event, the returned value 
will be :key-press. 

climreventp object Function 

Returns t if and only if object is an event. 

clim:+everywhere+ Constant 

The region that includes all the points on the infinite drawing plane. This is the 
opposite of clim:+nowhere+. 

clim:execute-frame-command frame command Generic Function 

clim:execute-frame-command executes the command command on behalf of the 
application frame frame. If you call clim:execute-frame-command from a process 
that is different from the process in which frame is running, CLIM will queue the 
command for later execution in frame's own process. 

The default method for clim:execute-frame-command simply applies to command 
name to the command arguments. You can specialize this function if you want to 
change the behavior associated with the execution of commands. 

clim:expand-presentation-type-abbreviation type &optional environment Function 

clim:expand-presentation-type-abbreviation is like climrexpand-presentation- 

type-abbreviation-1, except that type is repeatedly expanded until all presentation 
type abbreviations have been expanded. 

The optional argument environment conveys information about the local macro defi- 
nitions that might be defined by macrolet. It is used the same as it would be for 
macroexpand. 
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clim:expand-presentation-type-abbreviation-l type &optional environment Function 

If the presentation type specifier type is a presentation type abbreviation, or is an 
and, or, sequence, or climrsequence-enumerated that contains a presentation 
type abbreviation, then clim:expand-presentation-type-abbreviation-l expands the 
type abbreviation once, and returns two values, the expansion and t. If type is not 
a presentation type abbreviation, then the values type and nil are returned. 

The optional argument environment conveys information about the local macro defi- 
nitions that might be defined by macrolet. It is used the same as it would be for 
macroexpand. 



climrexpression Clim Presentation Type 

The presentation type used to represent any Lisp object. The textual view of this 
type looks like what the standard prinl and read functions produce and accept. 

This type has one option, :auto-activate, which controls whether the expression 
terminates on a delimiter gestures, or when the Lisp expression "balances" (for 
example, you type enough close parentheses to complete the expression). The de- 
fault for :auto-activate is nil, meaning that the user must use an activation ges- 
ture to terminate the input. 



clim:extended-input-stream-p object Generic Function 

Returns t if the object is a CLIM extended input stream, otherwise it returns nil. 

clim:extended-output-stream-p object Generic Function 

Returns t if the object is a CLIM extended output stream, otherwise it returns nil. 

clim:+fill+ Constant 

This constant can be used as a value to any of the min or max size options in 
clim:make-space-requirement or the layout pane macros. It indicates a pane's 
willingness to adjust an arbitrary amount in the specified direction (width or 
height). 



climrfilling-output f&optional stream &rest keys &key Ofill-width '(80 :character)J 

(■.break-characters '(#\Space)J : after-line-break : after-line-break-initially) &body body 

Function 

Binds stream to a stream that inserts line breaks into the output written to it so 
that the output is no wider then :fill-width. The filled output is then written on 
the stream that is the original value of stream, climrfilling-output does not split 
"words" across lines, so it can produce output wider than : fill-width. 
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"Words" are separated by the characters indicated by :break-characters. When a 
line is broken to prevent wrapping past the end of a line, the line break is made 
at one of these separators. 

stream The output stream; the default is *standard-output*. 

.■fill-width Specifies the width of filled lines. The default is 80 characters. It can be 
specified in one of the following ways: 

integer The width in device units (for example, pixels). 

string The spacing is the width of the string. 

function The spacing is the amount of space the function would con- 
sume when called on the stream. 

list The list is of the form (number unit), where unit is one of 

rpixel The width in pixels. 

rpoint The width in printers points. 

rcharacter The width of the "usual" character in the 
stream's current text style. 

If CLIM cannot find a break character that would make the output nar- 
row enough, the output might be wider than :fill-width 

.■break-characters 

Specifies a list of characters at which to break lines. The default in- 
cludes only the #\Space character. 

: after-line-break 

Specifies a string to be sent to stream after line breaks; the string ap- 
pears at the beginning of each new line. The string must not be wider 
than :fill-width. 

: after-line-break-initially 

Boolean option specifying whether the : after-line-break text is to be writ- 
ten to stream before doing body, that is, at the beginning of the first 
line; the default is nil. 

Here is an example of using climrfilling-output. Notice that this example uses 
clim:format-textual-list to generate the text to fill. 

(let ((stream xstandard-outputx) 

(alphabet '(abcdefghi j kl m 

nopqrstuvwxyz))) 
(cl im: f il 1 ing-output (stream :fill-width '(30 :character) ) 
(cl im: format-textual -1 ist alphabet tf'princ 

: stream stream 

: separator ", " : conjunction "and") 
(write-char #\. stream))) 
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climrfind-applicable-translators presentation input-context frame window x y &key 
-.event .-modifier-state :for-menu :fastp Function 

Returns a list of translators that apply to presentation in the input context input- 
context. Since input contexts can be nested, climrfind-applicable-translators iter- 
ates over all of contexts in input-context. See the section "Applicability of CLIM 
Presentation Translators". 

frame is the application frame, window, x, and y are the window the presentation 
is on, and the X and Y position of the pointer (respectively). 

■.event (which defaults to nil) is a pointer button event, and may be supplied to fur- 
ther restrict the set of applicable translators to only those whose gesture matches 
the pointer button event. 

■.modifier-state (which defaults to the current modifier state for the window) may 
also be supplied to restrict the set of applicable translators to only those who ges- 
ture matches the shift mask. Only one of -.event or -.modifier-state may be supplied. 

When :for-menu is t (the default), this returns every possible translator, disregard- 
ing -.event and -.modifier-state. 

When :fastp is t, this will simply return t if there are any translators. :fastp de- 
faults to nil. 



clinirfind-application-frame frame-name &rest initargs &key (.-create t) (.-activate t) 
(■own-process t) sport .-frame-manager .-frame-class &allow-other-keys Function 

Calling this function is similar to calling clinirniake-application-frame, and then 
calling clim:run-frame-top-level on the newly created frame. 

If .-create is t, a new frame will be created if one does not already exist. If .-create 
is rforce, a new frame will be created regardless of whether there is one already. 

If .-activate is t (the default), the frame's top level function will be invoked. If 
.-own-process is t (the default), the frame will run in its own process. 

.-port and .-frame-manager can be used to name the parent of the frame, .-frame-class 
is as for clim:make-application-frame. initargs are CLOS initargs that are passed 
along to clim:make-application-frame. 



clim:find-command-from-command-line-name name command-table &key (:errorp 
t) Function 

Given a command-line name name and a command-table, this function returns two 
values, the command name and the command table in which the command was 
found. If the command is not accessible in command-table and -.errorp is t, the 
clim:command-not-accessible condition will be signalled. 

name is a command-line name, command-table may be either a command table or a 
symbol that names a command table. 

clim:find-command-from-command-line-name ignores character case. 
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This function is the inverse of clim:command-line-name-for-command. 



clim:find-command-table name &key (serrorp t) Function 

Returns the command table named by name. If name is itself a command table, it 
is returned. If the command table is not found and serrorp is t, the 
clim:command-table-not-found condition will be signalled. 



clim:find-frame-manager &rest options &key sport (.server-path clim:*default- 
server-path*) &allow-other-keys Generic Function 

Finds a frame manager that is on the port sport, or creates a new one if none ex- 
ists. If sport is not supplied and a new port must be created, sserver-path may be 
supplied for use by clim:find-port. 

options may include other initargs for the frame manager. 

On Genera, you may supply the :gadget-menu-bar option. When you supply 
:gadget-menu-bar t, the Genera frame manager will use a toolkit-style menu bar. 
The default Genera frame manager does not use gadget-style menu bars. 



climrfind-innermost-applicable-presentation input-context stream x y &key (sframe 
clim:*application-frame*) smodifier-state sevent Function 

Given an input context input-context, an output recording window stream stream, 
and X and Y positions x and y, climrfind-innermost-applicable-presentation re- 
turns the innermost presentation that matches the innermost input context. See 
the section "Applicability of CLIM Presentation Translators". 

sframe is the application frame, smodifier-state is a mask that describes what shift 
keys are held down on the keyboard, and defaults to the window's current modifier 
state, sevent is a pointer button event. You may supply only one of smodifier-state 
or sevent. 



clim:find-keystroke-item keystroke command-table &key stest (serrorp t) Function 

Given a keystroke accelerator keystroke and a command-table, returns two values, 
the command menu item associated with the accelerator and the command table in 
which it was found. (Since keystroke accelerators are not normally inherited, the 
second returned value will usually be command-table.) keystroke is gesture spec, 
such as (:C : control : shift). 

stest specifies a function to use for looking up the items in the command table. It 
must be a function of two arguments, both of which are events or gesture specs. 
The default is a function that matches keyboard events against gesture names. 

If the keystroke accelerator is not present in any command table and serrorp is t, 
then the clim:command-not-accessible condition will be signalled, command-table 
may be either a command table or a symbol that names a command table. 
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clim:find-menu-item menu-name command-table &key (:errorp t) Function 

Given a menu-name and a command-table, return two values, the menu item and 
the command table in which it was found. (Since menus are not normally inherit- 
ed, the second returned value will usually be command-table.) If the command 
menu item is not present in any command table and :errorp is t, then the 
clim:command-not-accessible condition will be signalled, command-table may be 
either a command table or a symbol that names a command table. 

clim:find-named-color name palette &key :errorp Function 

Finds the color named name in the palette palette. The palette associated with the 
current application frame can be found by calling climrframe-palette. The re- 
turned value is a CLIM color object. 

If the color is not found and :errorp is t, the clim:color-not-found error is sig- 
nalled. Otherwise if the color is not found, this function returns nil. 

Palettes are described in more detail in "Predefined Color Names in CLIM". 



clim:find-pane-named frame pane-name &optional errorp Function 

Returns the pane named by pane-name in frame. If pane-name is a pane object, it 
is simply returned. This differs from clim:get-frame-pane in that the returned val- 
ue can be any pane type, not just a subclass of clim:clim-stream-pane. 

If the pane named pane-name is not found and :errorp is t, an error will be sig- 
nalled. Otherwise if :errorp is nil, the return value will be nil. 



climrfind-presentation-translators from-type to-type command-table Function 

Returns a list of all the translators in the command table command-table that 
translate from from-type to to-type, without taking into account any type parame- 
ters or testers, from-type and to-type must not be presentation type abbreviations. 



clim:find-port &rest initargs &key (.server-path clim:*default-server-path*J &al- 
low-other-keys Function 

Creates a port, a special object that acts as the "root" or "parent" of all CLIM 
windows and application frames. In general, a port corresponds to a connection to 
a display server. 

.server-path is a list that specifies the server path. The first element of the list is 
a keyword naming the type of port to be created (such as rgenera, :clx, or :cloe). 
The rest of the list are keyword-value pairs of options. 

In Genera, the only option is rscreen, which defaults to the main screen. If you 
are on a Genera Color system, and you give rscreen the value returned by 
colorrfind-color-screen, CLIM will create a color port. 

Under Cloe, the only supported port type is rcloe and there are no options. 
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If the CLX system (part of the X Remote Screen system) is loaded under Genera, 
the options are :host (a host name or object), and rdisplay (a display number) that 
identify the X Server to be used. 

Note: You should call clim:find-port only at runtime, not at load time. This 
function captures information about the screen currently in use. 

You may supply a :allow-loose-text-style-size-mapping initarg for any type of port 
to specify whether or not the port will use "loose" text style mapping. A port that 
uses "loose" text style mapping picks the closest available font size, rather than 
picking an exact font size. See the generic function clim:text-style-mapping. 



clim:+flipping-ink+ Constant 

A flipping ink that flips clim:+foreground-ink+ and clim:+background-ink+. You 
can think of this as an "xor" on monochrome displays. 



float &optional low high Clim Presentation Type 

The presentation type that represents a floating point number between low and 
high. This type is a subtype of climrreal. 



clim:+foreground-ink+ Constant 

An indirect ink that uses the medium's foreground design. 

climrform Clim Presentation Type 

The presentation type used to represent a Lisp form. This type is a subtype of 
climrexpression. It has one option, :auto-activate, which is treated the same way 
as the :auto-activate option to climrexpression. 



clim:formatting-cell f&optional stream &rest options &key (:align-x 'rleftj (:align-y 
':top) :min-width :min-height -.record-type &allow-other-keys) &body body Macro 

Establishes a "cell" context on the stream (which defaults to *standard-output*). 
All output performed on the stream within the extent of this macro will become 
the contents of one cell in a table. clim:formatting-cell must be used within the 
extent of clim:formatting-row, climrformatting-column, or clim:formatting-item- 
list. 

A cell can contain text, graphics, or both. The alignment keywords enable you to 
specify constraints that affect the placement of the contents of the cell. Each cell 
within a column may have a different alignment; thus it is possible, for example, 
to have centered legends over flush-right numeric data. 

For background information, examples, and overviews of related functions, see the 
section "Formatting Tables in CLIM". 
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stream 



:align-x 



:align-y 



:min-width 



The stream to which output should be sent. The default is 
*standard-output*. 

Specifies the horizontal placement of the contents of the cell. 
Can be one of: :left (the default), rright, or reenter. 

rleft means that the left edge of the cell is at the specified X 
coordinate, rright means that the right edge of the cell is at 
the specified X coordinate, reenter means that the cell is hori- 
zontally centered over the specified X coordinate. 

Specifies the vertical placement of the contents of the cell. Can 
be one of: rtop (the default), rbottom, or reenter. 

rtop means that the top of the cell is at the specified Y coor- 
dinate, rbottom means that the bottom of the cell is at the 
specified Y coordinate, reenter means that the cell is vertically 
centered over the specified Y coordinate. 

Specifies the minimum width of the cell. The default, nil, caus- 
es the width of the cell to be only as wide as is necessary to 
contain the cell's contents. 

:min-width can be specified in one of the following ways: 

Integer 

A size in the current units to be used for spacing. 

String or character 

The spacing is the width or height of the string or 
character in the current text style. 

Function 

The spacing is the amount of horizontal or vertical 
space the function would consume when called on the 
stream. 

List of form {number unit) 

The unit is rpoint, rpixel, or rcharacter. 



:min-height 



■.record-type 



Specifies the minimum height of the cell. The default, nil, 
causes the height of the cell to be only as high as is necessary 
to contain the cell's contents. 

:min-height is specified in the same way as :min-width. 



This option is useful when you have defined a customized 
record type to replace CLIM's default record type. It specifies 
the class of the output record to be created. 
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climrformatting-column f&optional stream &key :record-type) &body body Macro 

Establishes a "column" context on the stream (which defaults to *standard- 
output*). All output performed on the stream within the extent of this macro will 
become the contents of one column of the table, climrformatting-column must be 
used within the extent of climrformatting-table, and it must be used in conjunc- 
tion with clim:formatting-cell. 

For background information, examples, and overviews of related functions, see the 
section "Formatting Tables in CLIM". 



stream 



■.record-type 



The stream to which output should be sent. The default is 
*standard-output*. 

This option is useful when you have defined a customized 
record type to replace CLIM's default record type. It specifies 
the class of the output record to be created. 



clim:formatting-item-list f&optional stream &key :record-type :x-spacing :y-spacing 
.■initial-spacing :n-columns :n-rows :max-width :max-height .stream-width .stream- 
height (:row-wise t) (-.move-cursor t)) &body body Macro 

Establishes a "menu formatting" context on the stream (which defaults to 
*standard-output*). Use this macro to format the output in a tabular form when 
the exact ordering and placement of the cells is not important, climrformatting- 
item-list must be used with clim:formatting-cell. 

This macro expects its body to output a sequence of items using climrformatting- 
cell, which delimits each item. (You do not use climrformatting-column or 
clim:formatting-row within clim:formatting-item-list.) If no keyword arguments 
are supplied, CLIM chooses the number of rows and columns for you. You can 
specify a constraint such as the number of columns or the number of rows (but 
not both). Or you can constrain the size of the entire table display, by using :max- 
width or :max-height (but not both). If you specify one of these constraints, CLIM 
will adjust the table accordingly. 

For background information, examples, and overviews of related functions, see the 
section "Formatting Tables in CLIM". 

stream 

The stream to which output should be sent. The default is 
*standard-output*. 

:max-width 

Specifies the maximum width, in device units, of the table display. 

:max-height 

Specifies the maximum height, in device units, of the table display. 
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:n-rows 

Specifies the number of rows of the table. Specifying this overrides 
:max-width. 

:n-columns 

Specifies the number of columns of the table. Specifying this over- 
rides :max-height. 

:x-spacing 

Determines the amount of space inserted between columns of the 
table; the default is the width of a space character. :x-spacing can 
be specified in one of the following ways: 

Integer 

A size in the current units to be used for spacing. 

String or character 

The spacing is the width or height of the string or char- 
acter in the current text style. 

Function 

The spacing is the amount of horizontal or vertical space 
the function would consume when called on the stream. 

List of form (number unit) 

The unit is rpoint, rpixel, or rcharacter. 

.y-spacing 

Specifies the amount of blank space inserted between rows of the 
table; the default is the vertical spacing for the stream. The possi- 
ble values for this option are the same as for the :x-spacing option. 

.■initial-spacing 

When doing the layout, CLIM tries to evenly space items across the 
entire width of the stream. When this option is t, no whitespace is 
inserted before the first item on a line. 

:row-wise When this is nil, if there are multiple columns in the item list, the 
entries in the item list are arranged in a manner similar to entries 
in a phone book. Otherwise the entries are arranged in a "row- 
wise" fashion. The default is t. 

.stream-width 

The width of the stream (in device units). 

.stream-height 

The height of the stream (in device units). 

■.move-cursor 

When t (the default), CLIM moves the text cursor to the end (lower 
right corner) of the output. Otherwise, the cursor is left at the be- 
ginning (upper left corner) of the output. 
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clim:format-items items &key (.stream *standard-output*J sprinter .-presentation- 
type :x-spacing :y-spacing -.initial-spacing :n-rows :n-columns :max-width :max-height 
(:row-wise t) -.record-type (:cell-align-x 'rleftj (:cell-align-y ':top) Function 

Provides tabular formatting of a list of items. Each item in items is formatted as a 
separate cell within the table, items can be a list or a general sequence. 

For background information, examples, and overviews of related functions, see the 
section "Formatting Tables in CLIM". 

The options .stream, :x-spacing, :y-spacing, .-initial-spacing, :n-rows, :n-columns, 
:max-width, :max-height, :row-wise, and -.record-type are the same as for 
clim:formatting-item-list. 

Note that you must specify one of -.printer or -.presentation-type. 

-.printer A function that takes two arguments, an item and a stream. It 
should output the item to the stream. You cannot use this keyword 
option with -.presentation-type. 

-.presentation-type 

A presentation type. You cannot use this keyword option with -.print- 
er. 

The items will be printed as if -.printer were: 

#' (lambda (item stream) 

(cl im:present item presentation-type :stream stream)) 

:cell-align-x 

Supplies the :align-x option to an implicitly used climrformatting- 
cell. 

:cell-align-y 

Supplies the :align-y option to an implicitly used climrformatting- 
cell. 



clim:format-graph-from-roots root-objects object-printer inferior-producer &key 
(: stream *standard-output*J (.-orientation 'rhorizontalj -.center-nodes -.cutoff-depth 
-.merge-duplicates -.graph-type (-.duplicate-key #'identityj (-.duplicate-test #'eql) -.arc- 
drawer : arc-drawing-options : generation-separation iwithin-generation-separation 
-.maximize-generations (store-objects t) (-move-cursor t) Function 

Constructs and displays a directed, acyclic graph. The output from graph format- 
ting takes place in a normalized +Y-downward coordinate system. 

root-objects 

A sequence of the root elements of the set, from which the graph 
can be derived. 

object-printer 

A function of two arguments used to display each node of the 
graph. The function is passed the object associated with that node 
and the stream on which to do output. 
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inferior-producer 

A function that knows how to generate the inferiors (children) from 
a node object. It takes one argument, the node, and returns a list of 
inferior nodes. 

.stream Specifies the output stream; the default is *standard-output*. 

.■orientation 

Specifies rvertical or rhorizontal orientation for the "parent node 
to child node" direction of the graph display. The default for .-orien- 
tation is rvertical. 

:graph-type 

The type of the graph to be displayed, either rdigraph (the default 
when :merge-duplicates is t) or rtree (the default when :merge- 
duplicates is nil). 

:merge-duplicates 

When t, duplicate objects in the graph are displayed in the same 
node in the output. Otherwise, each object is given a unique node. 

■.center-nodes 

When t, the display of each node is placed at the center of the 
space allocated for it. The default, nil, causes each node to be 
placed in the upper left of the space allocated to it. 

:cutoff-depth 

An integer that specifies how many levels of each branch of the 
tree should be explored. The default is nil, which specifies no cut- 
off. 

■.duplicate-key 

Specifies the function used to extract the node object attribute used 
for duplicate comparison. The default is identity, that is, the object 
itself. 

■.duplicate-test 

Specifies the function used to test for duplicates comparison. The 
default is eql, that is, the object itself. 

■.generation-separation 

The amount of space to leave between successive generations of the 
graph. 

iwithin-generation-separation 

The amount of space to leave between nodes in the same generation 
of the graph. 

■.arc-drawer 

A function (taking 7 required arguments and a rest argument) used 
to draw the arc between nodes. The default is a function that be- 
have like clim:draw-line. The required arguments are: the stream, 
the "from" object, the "to" object, the "from" X and Y positions, 
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and the "to" X and Y positions. If .store-objects is nil, the "from" 
and "to" objects will be nil. The rest argument is a list of drawing 
options. 

.store-objects 

When this is t (the default), the objects will be stored in the graph 
and will be available to the arc drawing function. If the objects in 
your graph have dynamic extent or you require that they be subject- 
ed to garbage collection, you should supply : store-objects nil. 

■.move-cursor 

When t (the default), CLIM moves the text cursor to the end (lower 
right corner) of the output. Otherwise, the cursor is left at the be- 
ginning (upper left corner) of the output. 

For background information, examples, and overviews of related functions, see the 
section "Formatting Graphs in CLIM". 



clim:format-graph-from-root root-object object-printer inferior-producer &key 
(■.stream *standard-output*) (-.orientation 'rhorizontal) xenter-nodes xutoff-depth 
:merge-duplicates :graph-type Oduplicate-key&identity) (: duplicate-test #'eql) :arc- 
drawer : arc-drawing-options : generation-separation iwithin-generation-separation 
imaximize-generations (store-objects t) (-.move-cursor t) Function 

Like clim:format-graph-from-roots, except that root-object is a single root object 
instead of a sequence of roots. This function is provided only as a convenience. 



clim:format-textual-list sequence printer &key (stream *standard-output*) (sepa- 
rator ", ") .-conjunction Function 

Outputs a sequence of items as a textual list. For example, the list 

(12 3 4) 
could be printed as 

1, 2, 3, and 4 

The arguments provide control over the appearance of each element of the se- 
quence and over the separators used between each pair of elements. The separator 
string is output after every element but the last one. The conjunction is output be- 
fore the last element. 

sequence The sequence to output. 

printer is a function of two arguments: an element of the sequence and a 
stream. It is used to output each element of the sequence. 

.stream Specifies the output stream. The default is *standard-output*. 

.separator Specifies the characters to use to separate elements of a textual 
list. The default is " , " (comma followed by a space). 
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.■conjunction 

Specifies a string to use in the position between the last two ele- 
ments. Typical values are "and" and "or". It defaults to nil. 



clim:formatting-row f&optional stream &key :record-type) &body body 



Macro 



Establishes a "row" context on the stream (the default is *standard-output*). All 
output performed on the stream within the extent of this macro will become the 
contents of one row of a table. clim:formatting-row must be used within the ex- 
tent of clim:formatting-table, and it must be used in conjunction with 
clim:formatting-cell. 

For background information, examples, and overviews of related functions, see the 
section "Formatting Tables in CLIM". 



stream 



■.record-type 



The stream to which output should be sent. The default is 
*standard-output*. 

This option is useful when you have defined a customized 
record type to replace CLIM's default record type. It specifies 
the class of the output record to be created. 



clim:formatting-table f&optional stream &rest options &key :x-spacing :y-spacing 
srecord-type .-multiple-columns :multiple-columns-x-spacing :equalize-column-widths 
(■.move-cursor t)) &body body Macro 

Establishes a "table formatting" context on the stream (the default is *standard- 
output*). All output performed within the extent of this macro will be displayed in 
tabular form. This must be used in conjunction with clim:formatting-row or 
climrformatting-column, and clim:formatting-cell. 

For background information, examples, and overviews of related functions, see the 
section "Formatting Tables in CLIM". 



stream 



:x-spacmg 



The stream to which output should be sent. The default is 
*standard-output*. 

Determines the amount of space inserted between columns of 
the table; the default is the width of a space character. :x- 
spacing can be specified in one of the following ways: 

Integer 

A size in the current units to be used for spacing. 
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String or character 

The spacing is the width or height of the string or 
character in the current text style. 

Function 

The spacing is the amount of horizontal or vertical 
space the function would consume when called on the 
stream. 

List of form (number unit) 

The unit is rpoint, rpixel, or rcharacter. 



.■multiple-columns 



.y-spacmg 

Specifies the amount of blank space inserted between rows of 
the table; the default is the vertical spacing for the stream. 
The possible values for this option are the same as for the :x- 
spacing option. 

Is either nil, t, or an integer. If it is t or an integer, the table 
rows are broken up into multiple columns. If it is t, CLIM will 
determine the optimal number of columns. If it is an integer, 
it will be interpreted as the desired number of columns. 

:multiple-columns-x-spacing 

Controls the spacing between the multiple columns. This option 
defaults to the value of the :x-spacing option. It has the same 
format as :x-spacing. 

:equalize-column-widths 

When t, CLIM makes all the columns have the same width, 
which is the width of the widest cell in any column of the ta- 
ble. 



■.record-type 



.■move-cursor 



This option is useful when you have defined a customized 
record type to replace CLIM's default record type. It specifies 
the class of the output record to be created. 

When t (the default), CLIM moves the text cursor to the end 
(lower right corner) of the output. Otherwise, the cursor is left 
at the beginning (upper left corner) of the output. 



clim:frame-all-layouts frame 



Generic Function 



Returns a list of all of the layout names for frame. These are the names of the 
layouts that you use when you call setf on climrframe-current-layout. 



clim:frame-command-table frame 



Generic Function 
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Returns the name of the command table currently being used by the frame frame. 
You can use this function with setf to change the command table to be used. 



climrframe-current-layout frame Generic Function 

Returns the name of the current layout for frame. 

You can use setf on climrframe-current-layout to change the current layout. 

Note: changing the layout currently causes CLIM to throw out of the application's 
command loop, all the way back to clim:run-frame-top-level. This is done so that 
CLIM can perform some window management functions, such as rebinding I/O 
streams that correspond to the windows in the new layout. Therefore, when you 
call setf on climrframe-current-layout, you should only do so after you have done 
everything else in the sequence of operations and the application is prepared to re- 
turn to command input. 

climrframe-current-panes frame Generic Function 

Returns a list of all of the named CLIM stream panes that are contained in the 
current layout for the frame frame. The elements of the list will be CLIM pane 
objects. 

climrframe-error-output frame Generic Function 

Returns the value that should be used for *error-output* for frame. 

The default method (defined on climrapplication-frame) uses the first pane of type 
rapplication in the current layout. 

It can be useful to specialize climrframe-error-output on your own frame class 
when you want to use a different pane for *error-output*. 

climrdefault-frame-top-level calls this to determine what to bind *error-output* 

to. 



climrframe-exit frame Generic Function 

Exits from the application frame frame by signalling a climrframe-exit condition. 
If you call climrframe-exit from a process that is different from the process in 
which frame is running, CLIM will queue the request for later execution in 
frame's own process. 



climrframe-exit Class 

The condition signalled by climrframe-exit. 

climrframe-exit-frame frame-exit Generic Function 
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Returns the frame being exited from, frame-exit is a clim:frame-exit object. 



clim:frame-find-innermost-applicable-presentation frame input-context stream x y 

Generic Function 

Locates and returns the innermost applicable presentation on the window stream at 
the pointer position indicated by x and y, in the input context input-context, on be- 
half of the application frame frame. 

You can specialize this generic function for your own application frames. The de- 
fault method calls climrfind-innermost-applicable-presentation. 



clim:frame-input-context-button-press-handler frame stream button-press-event 

Generic Function 

This function is responsible for handling user pointer gestures on behalf of frame, 
stream is the window on which button-press-event took place. 

The default method on clim:standard-application-frame calls climrframe-find- 
innermost-applicable-presentation to find the innermost applicable presentation, 
and then calls climrthrow-highlighted-presentation to execute the translator that 
corresponds to the user's gesture. 



climrframe-maintain-presentation-histories frame Generic Function 

Returns t if the frame maintains histories for its presentations, otherwise returns 
nil. The default method on the class clim:standard-application-frame returns t if 
and only if the frame has an interactor pane. 

You can specialize this generic function for your own application frames. 



climrframe-manager Class 

The protocol class that corresponds to a frame manager. If you want to create a 
new class that obeys the frame manager protocol, it must be a subclass of 
climrframe-manager. 



climrframe-manager object Function 

Given a CLIM object object, climrframe-manager returns the frame manager asso- 
ciated with object. If object is not presently "owned" by any frame manager, 
climrframe-manager will return nil. 

You can call climrframe-manager on sheets and frames. 
climrframe-manager-dialog-view frame-manager Generic Function 
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Returns the view object that should be used to control the look-and-feel of 
climraccepting-values dialogs. Typically, this will be either clim:+textual-dialog- 
view+ or clim:+gadget-dialog-view+. 

You can use setf to change the default dialog view. 



clim:frame-manager-p object Generic Function 

Returns t if and only if object is of type climrframe-manager, otherwise returns 
nil. 



climrframe-manager-palette frame-manager Generic Function 

Returns the palette that will be used, by default, by all the frames managed by 
frame-manager, if those frame's don't have a palette of their own. You can use setf 
on this to change the frame manager's palette. 

A palette is an object that contains mappings from color names (which are strings 
or symbols) to CLIM color objects. See the section "Predefined Color Names in 
CLIM". 

The frame manager's palette defaults to the palette for its port, climrport-default- 
palette. 



clim:frame-name frame Generic Function 

Returns the name of the application frame. The name is a symbol. You can change 
the name of an application frame by using setf on clim:frame-name. 



climrframe-palette frame Generic Function 

Returns the palette associated with the application frame frame. The palette for a 
frame defaults to the default palette for the frame's frame manager. 

A palette is an object that contains mappings from color names (which are strings 
or symbols) to CLIM color objects. See the section "Predefined Color Names in 
CLIM". 

The frame's palette defaults to the palette for its frame manager, climrframe- 
manager-palette. 



climrframe-panes frame Generic Function 

Returns the single pane acting as the "root" pane for the current layout. 

The pane returned by this function will typically be some sort of layout pane, such 
as a clim:vbox-pane that holds the menu bar and the rest of the panes, or an 
clim:outlined-pane that serves as the border around an application frame. 
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climrframe-pointer-documentation-output frame Generic Function 

Returns the value that should be used for clim:*pointer-documentation-output* 
for frame. 

The default method (defined on clim:application-frame) uses the first pane of type 
rpointer-documentation in the current layout. 

clim:default-frame-top-level calls this to determine what to bind clim:*pointer- 
documentation-output* to. 



clim:frame-pretty-name frame Generic Function 

Returns the pretty name of the application frame. The pretty name is a string. You 
can change the pretty name of an application frame by using setf on climrframe- 
pretty-name. 



climrframe-replay frame stream &optional region Generic Function 

Replays all of the output records in stream's output history on behalf of the appli- 
cation frame frame that overlap the region region. If region is nil, all of the output 
records in the stream's viewport are replayed. 

You can specialize this generic function for your own application frames. The de- 
fault method for this calls climrstream-replay. 



clim:frame-query-io frame Generic Function 

Returns the value that should be used for *query-io* for frame. 

The default method (defined on clim:standard-application-frame) first tries to use 
the value returned by clim:frame-standard-input, and if it is nil, it uses the value 
returned by climrframe-standard-output. 

clim:default-frame-top-level calls this to determine what to bind *query-io* to. 

clim:frame-standard-input frame Generic Function 

Returns the value that should be used for *standard-input* for frame. 

The default method (defined on clim:standard-application-frame) uses the first 
pane of type clim:interactor-pane. If there are no interactor panes, the value re- 
turned by climrframe-standard-output is used. 

It is often useful to specialize climrframe-standard-input on your own frame class 
when you want to use a different pane for *standard-input*. 

clim:default-frame-top-level calls this to determine what to bind *standard-input* 

to. 



climrframe-standard-output frame Generic Function 
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Returns the value that should be used for *standard-output* for frame. 

The default method (defined on clim:standard-application-frame) uses the first 
pane of type clim:application-pane in the current layout. 

It is often useful to specialize climrframe-standard-output on your own frame 
class when you want to use a different pane for *standard-output*. 

clim:default-frame-top-level calls this to determine what to bind *standard- 
output* to. 



clim:frame-state frame Generic Function 

Returns one of renabled, rdisabled, rdisowned, or rshrunk, indicating the current 
state of frame. 

renabled means the frame currently enabled and visible on some port; this is the 
state that a frame is in when it is actively running, climrenable-frame causes a 
frame to enter the renabled state. 

rdisabled means that the frame is owned by a frame manager, but is not visible 
anywhere; this is the state that a frame is in when it has been exited but not de- 
stroyed, climrdisable-frame causes a frame to enter the rdisabled state. When a 
frame is initially created, it starts in the rdisabled state. 

rdisowned means that no frame manager owns the frame; this is the state a frame 
is in when it has been destroyed, climrdestroy-frame causes a frame to enter the 
rdisowned state. 

rshrunk means that the frame has been iconified. 



climrframe-top-level-sheet frame Generic Function 

Returns the window that corresponds to the top level window for the frame frame. 
This is the window that has as its children all of the panes of the frame. 

By default, all of the panes of an application frame share their event queue with 
the event queue of the frame's top level sheet. 



climrfuncall-presentation-generic-function presentation-function-name &body argu- 
ments Macro 

Funcalls the presentation generic function presentation-function-name with argu- 
ments arguments using funcall. 

The presentation-function-name argument is not evaluated. The value of presenta- 
tion-function-name can be any of the presentation generic functions defined by 
CLIM (climraccept, climrpresent, climrdescribe-presentation-type, 

climrpresentation-typep, climrpresentation-subtypep, 

climraccept-present-default, climrpresentation-type-specifier-p, 

climrpresentation-refined-position-test, or climrhighlight-presentation) or any 
presentation generic function you have defined yourself. 
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climrgadget Class 

The protocol class that corresponds to a gadget. 

See the section "Using Gadgets in CLIM". 

All subclasses of climrgadget must handle the four initargs rid, rclient, rarmed- 
callback, and rdisarmed-callback, which are used to specify, respectively, the gad- 
get id, client, armed callback, and disarmed callback of the gadget. 

The armed callback and disarmed callback are either nil or a function that takes a 
single argument, the gadget that was armed (or disarmed). 

climrgadget-active-p gadget Generic Function 

Returns t if the gadget is active, that is, available for input. Otherwise, it returns 
nil. 

climrgadget-client gadget Generic Function 

Returns the client of the gadget gadget. The client is usually an application frame, 
but it could be another gadget (for example, in the case of a push button that is 
contained in a radio box). 

You can use setf on climrgadget-client to change the gadget's client. 

climrgadget-dialog-view Class 

The class that represents the view that is used inside toolkit-style climraccepting- 
values dialogs. 

The gadget dialog view is one example of an indirect view. When you use this 
view when calling climraccepting-values, CLIM decodes the view into a more spe- 
cific view based on the presentation type. These more specific views include 
climr+radio-box-view+, climr+check-box-view+, climr+toggle-button-view+, 

climr+slider-view+, climr+text-field-view+, climr+text-editor-view+, climr+list- 
pane-view+, and climr+option-pane-view+. 

The following is a table of presentation types and the actual view they map to: 

Type Gadget 

climrcompletion climr+radio-box-view+ 

climrsubset-completion climr+check-box-view+ 

climrboolean climr+toggle-button-view+ 

real climr+slider-view+ 

float climr+slider-view+ 

integer climr+slider-view+ 

All others climr+text-field-view+ 

Try the following example in a CLIM Lisp Listener. 
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(defun gadget-dialog-test (&optional (stream xstandard-inputx)) 
(let ((dest :file) 
(name "") 
(strip nil )) 
(cl im:accepting-values (stream :al ign-prompts t) 

(setq dest (cl im: accept '(member :file :printer :window) 
:default dest :prompt "Destination type" 
:stream stream :view cl im:+gadget-dialog-view+)) 
(setq name (clim:accept 'string 

:default name :prompt "Destination name" 
:stream stream :view cl im:+text-f ield-view+)) 
(setq strip (clim:accept 'boolean 

:default strip :prompt "Strip text styles" 
:stream stream :view cl im:+gadget-dialog-view+))) 
(values dest name strip))) 



clim:+gadget-dialog-view+ Constant 

An instance of the class clim:gadget-dialog-view. Inside climraccepting-values, 
the default view for the dialog stream may be bound to clim:+gadget-dialog-view+. 



clim:gadget-id gadget Generic Function 

Returns the gadget id of the gadget gadget. The id is typically a simple Lisp object 
that uniquely identifies the gadget. 

You can use setf on clim:gadget-id to change the id of the gadget. 



clim:gadget-label labelled-gadget Generic Function 

Returns the label of the gadget labelled-gadget. The label must be a string or a 
pixmap. 

You can use setf to change the label of a gadget, but this may result in invoking 
the layout protocol on the gadget and its ancestor sheets (that is, the entire appli- 
cation frame may be re-layed out). 

clim:gadget-max-value range-gadget Generic Function 

Returns the maximum value of the gadget range-gadget, such as a slider. It will be 
a real number. 

You can use setf to change the maximum value of the gadget. 
clim:gadget-min-value range-gadget Generic Function 
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Returns the minimum value of the gadget range-gadget, such as a slider. It will be 
a real number. 

You can use setf to change the minimum value of the gadget. 



clim:gadget-menu-view Class 

The class that represents the view that is used inside toolkit-style menus. 

clim:+gadget-menu-view+ Constant 

An instance of the class clim:gadget-menu-view. Inside climrmenu-choose, the de- 
fault view for the menu stream may be bound to clim:+gadget-menu-view+. 

climrgadget-orientation oriented-gadget Generic Function 

Returns the orientation of the gadget oriented-gadget. Typically, this will be a key- 
word such as rhorizontal or rvertical. 

clim:gadget-value gadget Generic Function 

Returns the value of the gadget value-gadget. The interpretation of the value 
varies from gadget to gadget. For example, a scroll bar's value might be a number 
between and 1, while a toggle button's value is either t or nil. (The documenta- 
tion for each individual gadget specifies how to interpret the value.) 

You can use setf on clim:gadget-value to change the value of a gadget. When the 
value is changed, the value change callback will be called if you also specify 
rinvoke-callback t. 

For example, the following fragment is from a color chooser that has two sets of 
linked sliders, one of which selects the RGB components of a color and the other 
of which selects the IHS components. When a slider from one set is changed, the 
other slider set is updated. Updating the other slider set should not cause any call- 
backs to be invoked. 

(defmethod update-ihs ((frame color-chooser)) 
(with-slots (intensity hue saturation) frame 

(multiple-value-bind (ii hh ss) (cl im:color-ihs (color frame)) 
(setf (cl im: gadget-value intensity : invoke-cal lback nil) ii) 
(setf (cl im: gadget-value hue : invoke-cal lback nil) hh) 
(setf (cl im: gadget-value saturation : invoke-cal lback nil) ss)))) 



clim:gadget-view Class 

The class that represents gadget views. Gadgets views are used for toolkit-oriented 
applications. 
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clim:+gadget-view+ Constant 

An instance of the class clim:gadget-view. 

climrgadgetp object Generic Function 

Returns t if and only if object is of type climrgadget. 

clim:get-frame-pane frame pane-name &key (:errorp t) Function 

Returns the CLIM stream pane (that is, a pane that is a subclass of climrclim- 
stream-pane) named by pane-name in frame. If pane-name is a pane object, it is 
simply returned. 

If the pane named pane-name is not found and :errorp is t, an error will be sig- 
nalled. Otherwise if :errorp is nil, the return value will be nil. 

clim:global-command-table Clim Command Table 

The "global" command table from which all command tables inherit. 

clim:handle-event sheet event Generic Function 

Handles the event event on behalf of sheet. 

If you implement your own gadget classes, you will probably write one or more 
clim:handle-event methods that manage such things as pointer button presses, 
pointer motion into the gadget, and so on. For example, if you want to highlight a 
sheet in response to an event that informs it that the pointer has entered its ter- 
ritory, you might write a method on your sheet class and clim:pointer-enter-event 
that highlights the sheet, and another method on clim:pointer-exit-event that un- 
highlights the sheet. 

This function is called by CLIM's event dispatcher, so you will not generally need 
to call this function yourself. 

See the section "Using Gadgets in CLIM". See the section "Sheet Input Protocols". 

climrhandle-repaint sheet region Generic Function 

Implements repainting for a given sheet class, sheet is the sheet to repaint and re- 
gion is the region to repaint. 

If you implement your own gadget classes, you will probably write a climrhandle- 
repaint method that draws the gadget. This function is called by CLIM's event 
dispatcher, so you will not generally need to call this function yourself. 

See the section "Using Gadgets in CLIM". See the section "Sheet Input Protocols". 
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clim:hbox-pane Class 

The layout pane class that arranges its children in a horizontal row. 
climrhorizontally generates a pane of this type. 

In addition to the usual sheet initargs (the space requirement initargs, 
rforeground, rbackground, and :text-style), this class supports two other initargs: 

rspacing An integer that specifies the amount of space to leave between each 
of the child panes, in device units. 

rcontents A list of panes that will be the child panes of the box pane. 



clim:*help-gestures* Variable 

A list of gesture names that cause climraccept and clim:complete-input to display 
a help message, and, for some presentation types, the list of possibilities. On Gen- 
era, this includes the gesture corresponding to the ttsHelp character. 



climrhighlight-applicable-presentation frame stream input-context &optional 
(prefer-pointer-window t) Function 

This is the "input wait" handler used by clim:with-input-context. It is responsible 
for locating the innermost applicable presentation, unhighlighting presentations 
that are not applicable, and highlighting the presentation that is applicable, if 
there is one. 

frame is the application frame, stream is the output recording stream, and input- 
context is the input context. 

When prefer-pointer-window is t (the default), CLIM will use the window under the 
pointer instead of stream. This is the usual behavior. 



climrhighlight-output-record record stream state Generic Function 

CLIM calls this method in order to draw highlighting for the output record record 
on stream, state is either :highlight (meaning to draw the highlighting) or 
runhighlight (meaning to erase the highlighting). 

The default method (on CLIM's basic output record class) simply draws a rectan- 
gle around the bounding rectangle of record. Some displayed output records provide 
their own methods, for example, output records for ellipses implement a method 
that draws a slightly larger ellipse around the ellipse being highlighted. 

The following example shows how you might implement this method for an output 
record that records a filled-in circle: 
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(def method cl i m : hi ghl ight-output- record 

((record circle-output-record) stream state) 
(declare (ignore state)) 
(multiple-value-bind (xoff yoff) 

(cl i m : convert- f rom-rel ati ve-to-absol ute-coordi nates 
stream (cl im: output-record-parent record)) 
(with-slots (center-x center-y radius) record 

(cl im:with-output-recording-options (stream : record nil) 
(cl im:draw-ci rclex 

stream (+ center-x xoff) (+ center-y yoff) (+ radius 2) 
:filled nil :ink cl im:+fl ipping-ink+))))) 



climrhighlight-presentation type-key parameters options type record stream state 

Clim Presentation Method 

This method is responsible for drawing a highlighting box for the presentation 
record on the stream stream, state will be either rhighlight or runhighlight, mean- 
ing that the highlighting box should either be drawn or erased. 

It can be useful to define a climrhighlight-presentation method when you want to 
have special highlighting behavior, such as "inverse video", for a presentation 
type. 

Here is an example from an application that displays the floor plan of a suite of 
offices. In one pane, there is a list of the names of the people in the offices, and 
in another pane there is the floor plan itself. When a user waves the mouse over 
either pane, the relevant office and names are highlighted in both panes. 

(cl im:def ine-presentati on-type room ()) 

(cl im : def ine-presen tat ion-method cl i m : hi ghl ight-presentation 
((type room) record stream state) 
(declare (ignore state)) 

(let ((room (cl im:presentation-object record))) 
(cl im:draw-polygonx stream (room-coords room) 
:ink cl im:+fl ipping-ink+) 
(when (room-associated-people room) 

(let ((stream (cl im: get-frame-pane cl im:*appl ication-f ramex 'people))) 
(cl im:with-output-recording-options (stream : record nil) 
(dolist (person (room-associated-people room)) 

(let ((person-presentation (person-directory-presentation person))) 
(when person-presentation 

(cl im:with-bounding-rectanglex (rl rt rr rb) 
person-presentati on 
(cl im:draw-rectanglex stream rl rt rr rb 

: ink cl im:+fl ipping-ink+)))))))))) 

(cl im:def ine-presentati on-type person ()) 
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(cl im:def ine-presen tat ion-method cl i m : hi ghl ight-p reservation 
((type person) record stream state) 
(declare (ignore state)) 

(cl im:with-bounding-rectanglex (rl rt rr rb) record 
(cl im:draw-rectanglex stream rl rt rr rb 

:ink cl im:+fl ipping-ink+)) 
(let ((person (cl im:presentation-object record))) 
(when (person-office person) 

(let ((stream (cl im: get-frame-pane cl im:*appl ication-f ramex 'map)) 
(office (person-office person))) 
(cl im:with-output-recording-options (stream : record nil) 
(cl im:draw-polygonx stream (room-coords office) 

:ink cl im:+fl ipping-ink+)))))) 



climrhorizontally f&rest options &key .spacing &allow-other-keys) &body contents 

Macro 

The climrhorizontally macro lays out one or more child panes horizontally, from 
left to right. The climrhorizontally macro serves as the usual interface for creat- 
ing an climrhbox-pane. 

.spacing is an integer that specifies how much space should be left between each 
child pane, in device units, options may include other pane initargs, such as space 
requirement options, rforeground, rbackground, rtext-style, and so forth. 

contents is one or more forms that produce the child panes. Each form in contents 
is of the form: 

• A pane. The pane is inserted at this point and its space requirements are used 
to compute the size. 

• A number. The specified number of device units should be allocated at this 
point. 

• The symbol climr+fill+. This means that an arbitrary amount of space can be 
absorbed at this point in the layout. 

• A list whose first element is a number and whose second element evaluates to a 
pane. If the number is less than 1, then it means that that percentage of excess 
space or deficit should be allocated to the pane. If the number is greater than 
or equal to 1, then that many device units are allocated to the pane. For exam- 
ple: 

(cl im:horizontal ly () 

(1/3 (cl im:make-pane 'label -button-pane)) 
(2/3 (cl im:make-pane 'label -button-pane))) 
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would create a horizontal row of two "label button" panes. The first pane takes 
one-third of the space, and the second takes two-thirds of the space. 

See the section "Using the :LAYOUTS Option to CLIM:DEFINE-APPLICATION- 
FRAME". 



clim:+hyper-key+ Constant 

The modifier state bit that corresponds to the user holding down the hyper key on 
the keyboard. See the section "Operators for Gestures in CLIM". 



clim:+identity-transformation+ Constant 

An instance of a transformation that is guaranteed to be an identity transforma- 
tion, that is, the transformation that "does nothing". 



clim:identity-transformation-p transform Generic Function 

Returns t if transform is equal (in the sense of clim:transformation-equal) to the 
identity transformation, otherwise returns nil. 



climrimmediate-rescan input-editing-stream Generic Function 

Invokes a rescan operation immediately on input-editing-stream by "throwing" out 
to the beginning of the most recent invocation of clim:with-input-editing. 

For more information on the input editor, see the section "The Structure of the 
CLIM Input Editor". 



climrindenting-output (stream indentation &key (:move-cursor t)) &body body 

Function 

Binds stream to a stream that inserts whitespace at the beginning of each line, 
and writes the indented output to the stream that is the original value of stream. 

stream The output stream. 

indentation 

What gets inserted at the beginning of each line output to the 
stream. Four possibilities exist: 

integer The width in device units (for example, pixels). 

string The spacing is the width of the string. 

function The spacing is the amount of space the function would 
consume when called on the stream. 

list The list is of the form (number unit), where unit is one 

of 
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rpixel The width in pixels. 

rpoint The width in printers points. 

rcharacter The width of the "usual" character in 
the stream's current text style. 

:move-cursor 

When t (the default), CLIM moves the text cursor to the end (lower 
right corner) of the output. Otherwise, the cursor is left at the be- 
ginning (upper left corner) of the output. 

You should begin the body with (terpri stream) (or the equivalent) to position the 

stream to the initial indentation. 

Note: if you use climrindenting-output in conjunction with climrfilling-output, 
you should put the call to climrindenting-output outside of the call to climrfilling- 
output. This is necessary because climrfilling-output does not track what sort of 
output is being done inside it, except for pure textual output. 

climr*input-context* Variable 

The current input context, which describes the presentation type(s) currently being 
input by CLIM. climr*input-context* gets bound by calls to climrwith-input- 
context. 

climr*input-context* is a list, each element of which is a list consisting of a pre- 
sentation type and a tag. The tag corresponds to a point in the control structure 
of CLIM at which that input context for the presentation type was established. 
The first element of climr*input-context* is the most recently establish context, 
and the last element is the oldest context. 

The value of climr*input-context* and all of the sublists within climr*input- 
context* have dynamic extent. 

climrinput-context-type context-entry Function 

Given one element from climr*input-context*, context-entry, this returns the pre- 
sentation type of the context entry. 



climrinput-editor-format input-editing-stream format-string &rest format-args 

Function 

This function is like format, except that it is intended to be called on input edit- 
ing streams. It arranges to insert "noise strings" in the input editor's input buf- 
fer. You can use this to display in-line prompts in climraccept methods. 

For more information on the input editor, see the section "The Structure of the 
CLIM Input Editor". 
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clim:input-not-of-required-type Condition 

This condition is signalled when CLIM gets input that does not satisfy the speci- 
fied type while inside of climraccept. It is built on conditions:parse-error. 



clim:input-not-of-required-type object type Function 

Reports that input does not satisfy the specified type, object is a parsed object or 
an unparsed token (a string), type is a presentation type specifier. This function 
does not return. 



clim:input-stream-p stream Generic Function 

Returns t if the object passed in is a CLIM basic input stream. 

clim:input-editing-stream-p object Generic Function 

Returns t if the object is a CLIM input editing stream, that is, the sort of stream 
created by clim:with-input-editing. 

integer &optional low high Clim Presentation Type 

The presentation type that represents an integer between low and high. Options to 
this type are :base (default 10) and rradix (default nil), which correspond to 
*print-base* and *print-radix*, respectively. It is a subtype of rational. 

clim-lisp:interactive-stream-p stream Generic Function 

Returns t if object is an interactive stream, that is, a bidirectional stream intended 
for user interactions. Otherwise it returns nil. This is exactly the same function as 
in Common Lisp, except that in CLIM it is a generic function. 

CLIM's input editor is intended to work only on interactive streams. 

clim:interactor-pane Class 

The pane class that is used to implement "interactor" panes. This is the type of 
pane created by clim:make-clim-interactor-pane, and corresponds to the pane type 
abbreviation rinteractor in the rpanes clause of clim:define-application-frame. 
The default method for clim:frame-standard-input will return the first pane of 
this type in a frame. 

For clim:interactor-pane, the default for the :display-time option is nil, and the 
default for the :scroll-bars option is rvertical. 

See the section "Using the rpanes Option to climrdefine-application-frame'. 
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climrinvert-transformation transform Generic Function 

Returns a transformation that is the inverse of transform. The result of composing 
a transformation with its inverse is the identity transformation. 

If transform is singular, climrinvert-transformation signals the climrsingular- 

transformation condition, with a named restart that is invoked with a transforma- 
tion and makes climrinvert-transformation return that transformation. This is to 
allow a drawing application, for example, to use a generalized inverse to transform 
a region through a singular transformation. 

With finite-precision arithmetic there are several conditions that might occur dur- 
ing the attempt to invert a singular or "almost singular" transformation. These 
include computation of a zero determinant, floating-point underflow during compu- 
tation of the determinant, or floating-point overflow during subsequent multiplica- 
tion.) climrinvert-transformation signals the climrsingular-transformation error 
for all of these cases. 



climrinvertible-transformation-p transform Generic Function 

Returns t if transform has an inverse, otherwise returns nil. 

climrinvoke-with-drawing-options stream continuation &rest options 

Generic Function 

The functional equivalent of climrwith-drawing-options. This binds the stream's 
drawing options to the new drawing options specified by options, options may in- 
clude any of the drawing options allowed in climrwith-drawing-options. When the 
drawing options are in effect, continuation is called, continuation is a function of 
zero arguments. 

The returned value is the value returned by continuation. 

See the macro climrwith-drawing-options. 

climrinvoke-with-new-output-record stream continuation record-type constructor 
&rest initargs &key .-parent &allow-other-keys Generic Function 

The functional equivalent of climrwith-new-output-record. This creates a new out- 
put record of type record-type using the supplied initargs. If constructor is not nil, 
it is a constructor function that creates the new output record. 

When the record has been created, continuation is called in order to create the 
contents of the record, continuation is a function of one argument, the stream. 

The returned value is the value returned by continuation. 

See the macro climrwith-new-output-record. 



climrinvoke-with-output-recording-options stream continuation record draw 

Generic Function 
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The functional equivalent of climrwith-output-recording-options. This binds 
recording and drawing state of the stream stream to the new state record and 
draw, and then calls the continuation, continuation is a function of zero arguments. 

The returned value is the value returned by continuation. 

See the macro climrwith-output-recording-options. 

clim:invoke-with-text-style medium style continuation original-stream 

Generic Function 

The functional equivalent of clim:with-text-style. This binds the current text style 
of medium to the new text style style, and then calls the continuation, continuation 
is a function of one argument, the stream. 

The returned value is the value returned by continuation. 

See the macro clim:with-text-style. 

clim:key-press-event Class 

The class that corresponds to pressing a key on the keyboard. This is a subclass of 
clim:keyboard-event. 

clim:key-release-event Class 

The class that corresponds to releasing a key on the keyboard. This is a subclass 
of clim:keyboard-event. 

clim:keyboard-event Class 

The class that corresponds to a keyboard event. This is a subclass of climrdevice- 
event. 

clim:keyboard-event-character keyboard-event Generic Function 

Returns the character corresponding to the key that was pressed or released, if 
there is a corresponding character in the Common Lisp character set. If there is 
no corresponding Common Lisp character, this will return nil. 

clim:keyboard-event-key-name keyboard-event Generic Function 

Returns the name of the key that was pressed or released in order to generate the 
keyboard event. The name of the key will be a symbol. 

keyword Clim Presentation Type 
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The presentation type that represents a symbol in the keyword package. It is a 
subtype of symbol. 



clim:labelled-gadget-mixin Class 

The class that is mixed into a gadget that has a label, for example, a push button. 
The label may be a string, a pattern, or a pixmap. 

All subclasses of clim:labelled-gadget-mixin must handle the initargs rlabel, 
ralignment, and :text-style, which are used to specify the label, the label's align- 
ment within the gadget, and the label's text style. 



climrlabelling f&rest options &key .-label (:label-alignment rbottomj &allow-other- 
keysj &body contents Macro 

Creates a vertical stack consisting of two panes. One pane contains the specified 
label, which is a string, a pattern, or a pixmap. The other pane is specified by con- 
tents. 

The climrlabelling macro is the usual way of creating a pane of type climrlabel- 
pane. 

options may include other pane initargs, such as space requirement options, 
rforeground, rbackground, rtext-style, and so forth. 



climrline Class 

The protocol class that corresponds to a mathematical line-segment, that is, a poly- 
line with only a single segment. This is a subclass of climrpolyline. If you want to 
create a new class that obeys the line protocol, it must be a subclass of climrline. 



climrlinep object Generic Function 

Returns t if and only if object is of type climrline. 

climrline-end-point line Generic Function 

Returns the ending point of line. 

climrline-end-point* line Generic Function 

Returns the ending point of line as two values representing the coordinate pair. 

climrline-start-point line Generic Function 

Returns the starting point of line. 
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clim:line-start-point* line Generic Function 

Returns the starting point of line as two values representing the coordinate pair. 

clim:line-style Class 

The class that represents line styles. 

clim:line-style-cap-shape line-style Generic Function 

Returns the cap shape component of a line style object. This will be one of :butt, 
rsquare, rround, or :no-end-point. See the section "CLIM Line Style Suboptions". 

clim:line-style-dashes line-style Generic Function 

Returns the dashes component of a line style object. This will be nil to indicate a 
solid line, t to indicate a dashed line whose dash pattern is unspecified, or will be 
a sequence specifying some sort of a dash pattern. See the section "CLIM Line 
Style Suboptions". 

clim:line-style-joint-shape line-style Generic Function 

Returns the joint shape component of a line style object. This will be one of 
rmiter, rbevel, rround, or rnone. See the section "CLIM Line Style Suboptions". 

clim:line-style-p object Generic Function 

Returns t if and only if object is of type climrline-style. 

climrline-style-thickness line-style Generic Function 

Returns the thickness component of a line style object, which is an integer. See 
the section "CLIM Line Style Suboptions". 

clim:line-style-unit line-style Generic Function 

Returns the unit component of a line style object, which will be one of mormal or 
rpoint. See the section "CLIM Line Style Suboptions". 

clim:list-pane Class 

The clim:list-pane gadget class corresponds to a list pane, that is, a pane whose 
semantics are similar to a radio box or check box, but whose visual appearance is 
a list of buttons. It is a subclass of climrvalue-gadget. 

See the section "Using Gadgets in CLIM". 
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In addition to the initargs for climrvalue-gadget and the usual pane initargs 
(rforeground, rbackground, :text-style, space requirement options, and so forth), 
the following initargs are supported: 

:mode Either :one-of or :some-of. When it is :one-of, the list pane acts 
like a radio box, that is, only a single item can be selected. Other- 
wise, the list pane acts like a check box, in that zero or more items 
can be selected. The default is :one-of. 

ritems A list of items. 

:name-key 

A function of one argument that generate the name of an item from 
the item. The default is princ-to-string. 

rvalue-key 

A function of one argument that generate the value of an item from 
the item. The default is identity. 

rtest A function of two arguments that compares two items. The default 

is eql. 

Calling climrgadget-value on a list pane will return the single selected item when 
the mode is :one-of, or a sequence of selected items when the mode is :some-of. 

The climrvalue-changed-callback is invoked when the select item (or items) is 
changed. 

Here are some examples of list panes: 

(cl im: make-pane 'cl im: 1 ist-pane 
:value "Symbolics" 
:test 'string= 

: val ue-changed-cal 1 back ' 1 i st-pane-changed-cal 1 back 
litems '("Franz" "Lucid" "Harlequin" "Symbolics")) 

(cl im:make-pane 'cl im: 1 ist-pane 
: value ' ("Lisp" "C++") 
:mode :some-of 

: val ue-changed-cal 1 back ' 1 i st-pane-changed-cal 1 back 
: items '("Lisp" "Fortran" "C" "C++" "Cobol" "Ada")) 

(defun 1 i st-pane-changed-cal 1 back (tf value) 

(format t "~&List pane ~A changed to ~S" tf value)) 



clim:list-pane-view Class 

The class that represents the view corresponding to a list pane. List panes are an- 
other way of representing "one of" or "some of" fields. 
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clim:+list-pane-view+ Constant 

An instance of the class clim:list-pane-view. 



clim:lookup-keystroke-command-item keystroke command-table &key :test (.-numer- 
ic-argument I) Function 

This is like clim:lookup-keystroke-item, except that it searches only for enabled 
commands. If it cannot find an accelerator associated with an enabled command, 
clim:lookup-keystroke-command-item returns nil. 

-.test is a function of two arguments used to compare the keystroke to the gestures 
in the command table. It defaults to clim:event-matches-gesture-name-p. 

■.numeric-argument is the accumulated numeric argument. It will be substituted for 
any occurrences of clim:*numeric-argument-marker* in the resulting command. 



clim:lookup-keystroke-item keystroke command-table &key :test Function 

This is like clim:find-keystroke-item, except that it descends into sub-menus in 
order to find a keystroke accelerator matching keystroke. If it cannot find any such 
accelerator, clim:lookup-keystroke-item returns nil. 

-.test is a function of two arguments used to compare the keystroke to the gestures 
in the command table. It defaults to clim:event-matches-gesture-name-p. 

clim:make-3-point-transformation point-1 point-2 point-3 point-1-image points- 
image point-3-image Function 

Makes a transformation that takes point-1 into point- 1-image, point-2 into points- 
image and point-3 into point-3-image. (Three non-collinear points and their images 
under the transformation are enough to specify any affine transformation.) 

It is an error for point-1, point-2, and point-3 to be collinear; if they are collinear, 
the climrtransformation-underspecified condition is signalled. If point- 1-image, 
point-2-image, and point-3-image are collinear, the resulting transformation will be 
singular, but this is not an error. 

clim:make-3-point-transformation* xl yl x2 y2 x3 y3 xl-image yl-image x2-image 
y2-image x3-image y3-image Function 

Makes a transformation that takes (xl, yl) into (xl-image, yl-image), (x2, y2) into 
(x2-image, y2-image) and (x3, y3) into (x3-image, y3-image). (Three non-collinear 
points and their images under the transformation are enough to specify any affine 
transformation.) 

It is an error for (xl, yl), (x2, y2) and (x3, y3) to be collinear; if they are collinear, 
the climrtransformation-underspecified condition is signalled. If (xl-image, yl- 
image), (x2-image, y2-image), and (x3-image, y3-image) are collinear, the resulting 
transformation will be singular, but this is not an error. 
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clim:make-application-frame frame-name &key .-frame-class :pretty-name .-parent 
.-left stop .-right .-bottom .-height .-width &allow-other-keys Function 

Makes an instance of the application frame of type .-frame-class. In addition to the 
keyword arguments listed, you can also supply initialization arguments for .-frame- 
class. The keyword arguments not handled by clim:make-application-frame are 
passed as initargs to closrmake-instance. 

frame-name 

A symbol. This will be the same as one of the name arguments 
to clim:define-application-frame. 



.-frame-class 

The class to instantiate, defaults to frame-name. 
purposes you can supply a subclass of frame-name. 



For special 



:pretty-name 

A string that is used as a title. It defaults to a "prettified" 
version of frame-name. 

.-parent The "parent" of the application. This can be either a port or a 
frame manager. If it is not supplied, it defaults to the current 
port. You should provide this argument when you want to cre- 
ate an application frame on some display server other than the 
current one, or with a non-default frame manager. See the 
function clim:find-port and the function clim:find-frame- 
manager. 

.-left, stop, .-right, .-bottom 

The coordinates of the left, top, right, and bottom edges of the 
frame, in device units, deft and stop default to 0, and .-right and 
.-bottom default to nil. 

.-width, .-height 

The size of the frame in device units, .-width and .-height de- 
fault so that the frame will fill the entire screen. 



climrmake-bounding-rectangle xl yl x2 y2 



Function 



Makes an object of class climrstandard-bounding-rectangle whose edges are par- 
allel to the coordinate axes. One corner is at (xl,yl) and the opposite corner is at 

(x2,y2). 

The representation of rectangles in CLIM is chosen to be efficient. CLIM repre- 
sents rectangles by storing the coordinates of two opposing corners of the rectan- 
gle. Because this representation is not sufficient to represent the result of arbi- 
trary transformations of arbitrary rectangles, CLIM is allowed to return a polygon 
as the result of such a transformation. (The most general class of transformations 
that is guaranteed to always turn a rectangle object into another rectangle object 
is the class of transformations that satisfy clim:rectilinear-transformation-p.) 



clim:make-ihs-color intensity hue saturation 
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Function 



Creates a color object, intensity is a real number between and the square root of 
3 inclusive, hue and saturation are real numbers between and 1 inclusive. 



clim:make-rgb-color red green blue 



Function 



Creates a color object, red, green, and blue are real numbers between and 1 in- 
clusive that specify the values of the corresponding color components. 



clim:make-clim-application-pane &rest options 

Like clim:make-clim-stream-pane, except that 
clim:application-pane. 



the type is 



Macro 
forced to be 



clim:make-clim-interactor-pane &rest options 



Macro 



Like clim:make-clim-stream-pane, except that the type is forced to be 
clim:interactor-pane. 



clim:make-clim-stream-pane &rest options &key (:type "clim:clim-stream-pane) 

.-label (.-label-alignment rbottom) (.scroll-bars ': vertical) (-borders t) .spacing sdisplay- 
after-commands &allow-other-keys Macro 

Creates a pane of type -.type, which defaults to clim:clim-stream-pane. 

If -.label is supplied, it is a string used to label the pane, -.label-alignment is either 
rbottom or :top, and specifies whether to place the label at the bottom or top of 
the window. 

-.scroll-bars may be t to indicate that both vertical and horizontal scroll bars should 
be included, rvertical (the default) to indicate that vertical scroll bars should be 
included, or rhorizontal to indicate that horizontal scroll bars should be included. 
If -.scroll-bars is :none, the pane will be scrollable but will not have scroll bars. If 
-.scroll-bars is nil, the pane will not be scrollable. 

If -.borders is t, the pane will have a border drawn around it. 

: display-after-commands may be t (meaning that the pane should be redisplayed af- 
ter each command is executed), nil (meaning that the pane should not be redis- 
played except by an explicit call to clim:redisplay-frame-pane), or :no-clear 
(which is like t, except that the pane is not cleared before the display function is 
called). 

Other options may include all of the valid CLIM application pane options, includ- 
ing rincremental-redisplay, the space requirement initargs, rforeground, 
rbackground, :text-style, and so forth. 



Page 1568 



clim:make-command-table name &key :inherit-from :menu :inherit-menu (:errorp t) 

Function 

Creates a command table named name that inherits from dnherit-from and has a 
menu specified by :menu. dnherit-from, :menu, and dnherit-menu are as for 
clim:define-command-table. If the command table already exists and :error-p is t, 
then a clim:command-table-already-exists condition will be signalled. 



clim:make-contrasting-dash-patterns n &optional k Function 

Makes a simple vector of n dash patterns with recognizably different appearances. 

If k (an integer between and n-1) is supplied, clim:make-contrasting-dash- 
patterns returns the k'th dash pattern. 

If the implementation does not have n different contrasting dash patterns, 
clim:make-contrasting-dash-patterns signals an error. This will not happen un- 
less n is greater than sixteen. 

clim:make-contrasting-inks n &optional k Function 

Makes a simple vector of n inks with different appearances. 

If k (an integer between and n-1) is supplied, clim:make-contrasting-inks re- 
turns the £'th design. 

If the implementation does not have n different contrasting inks, climrmake- 
contrasting-inks signals an error. This will not happen unless n is greater than 
eight. 

The rendering of the design may be a color or a stippled pattern, depending on 
whether the output medium supports color. 

clim:make-design-from-output-record record Function 

Makes a design that replays the output record record when the design is drawn by 
climrdraw-design. 

Presently, only output records whose displayed representation consists only of 
graphics (such as the output records created by clim:draw-line* and climrdraw- 
ellipse*) can be turned into designs by clim:make-design-from-output-record. 

You can use climrtransform-region on the result of clim:make-design-from- 

output-record in order to apply a transformation to it. 



climrmake-ellipse center-point radius-1-dx radius-1-dy radius-2-dx radius-2-dy &key 
.start-angle :end-angle Function 

Makes an object of class climrstandard-ellipse. The center of the ellipse is center- 
point. 
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This function is the same as climrmake-ellipse* except that the location of the 
center of the ellipse is specified as a point rather than as X and Y coordinates. 



climrmake-ellipse* center-x center-y radius-1-dx radius-1-dy radius-2-dx radius-2-dy 
&key .start-angle :end-angle Function 

Makes an object of class climrstandard-ellipse. The center of the ellipse is 
{center-x, center-y). 

Two vectors, (radius-1-dx, radius-1-dy) and (radius-2-dx, radius-2-dy) specify the 
bounding parallelogram of the ellipse as explained above. It is an error for those 
two vectors to be collinear (in order for the ellipse to be well-defined). The special 
case of an ellipse with its axes aligned with the coordinate axes can be obtained by 
setting both radius-1-dy and radius-2-dx to 0. 

If .start-angle or :end-angle are supplied, the ellipse is the "pie slice" area swept 
out by a line from the center of the ellipse to a point on the boundary as the 
boundary point moves from .start-angle to :end-angle. Angles are measured counter- 
clockwise with respect to the positive X axis. If :end-angle is supplied, the default 
for .start-angle is 0; if .start-angle is supplied, the default for :end-angle is 2pi; if 
neither is supplied then the region is a full ellipse and the angles are meaningless. 

See the section "Ellipses and Elliptical Arcs in CLIM". 



clim:make-elliptical-arc center-point radius-1-dx radius-1-dy radius-2-dx radius-2-dy 
&key .start-angle :end-angle Function 

Makes an object of class clim:standard-elliptical-arc. The center of the ellipse is 
center-point. 

This function is the same as clim:make-elliptical-arc* except that the location of 
the center of the arc is specified as a point rather than as X and Y coordinates. 



clim:make-elliptical-arc* center-x center-y radius-1-dx radius-1-dy radius-2-dx ra- 
dius-2-dy &key .start-angle :end-angle Function 

Makes an object of class clim:standard-elliptical-arc. The center of the ellipse is 
(center-x, center-y) . 

Two vectors, (radius-1-dx, radius-1-dy) and (radius-2-dx, radius-2-dy), specify the 
bounding parallelogram of the ellipse as explained above. It is an error for those 
two vectors to be collinear (in order for the ellipse to be well-defined). The special 
case of an elliptical arc with its axes aligned with the coordinate axes can be ob- 
tained by setting both radius-1-dy and radius-2-dx to 0. 

The arc is swept from .start-angle to :end-angle. Angles are measured counter- 
clockwise with respect to the positive X-axis. If :end-angle is supplied, the default 
for .start-angle is 0; if .start-angle is supplied, the default for :end-angle is 2pi; if 
neither is supplied then the region is a closed elliptical path and the angles are 
meaningless. 
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See the section "Ellipses and Elliptical Arcs in CLIM". 



clim:make-flipping-ink designl design2 Function 

Returns a design that interchanges occurrences of two designs. Drawing this de- 
sign over a background changes the color in the background that would have been 
drawn by designl at that point into the color that would have been drawn by de- 
sign2 at that point, and vice versa. 

In the present implementation, both designs must be colors. On the basic CLX 
port, only clim:+flipping-ink+ is supported at present. 



clim:make-gray-color luminosity Function 

Creates a color object whose "brightness" is luminosity, luminosity is a real num- 
ber between and 1 inclusive. means black and 1 means white. 



clim:make-line start-point end-point Function 

Makes an object of class clim:standard-line that connects start-point to end-point. 

clim:make-line* start-x start-y end-x end-y Function 

Makes an object of class clim:standard-line that connects (start-x, start-y) to (end- 
x, end-y). 



clim:make-line-style &key (:unit rnormal) (.-thickness I) sdashes (:joint-shape rmiter) 
(xap-shape :butt) Function 

Creates a line style object with the supplied characteristics. 

For information about the keyword arguments, see the section "CLIM Line Style 
Suboptions". 

These line style keywords correspond to the CLIM line style suboptions that begin 
with ":line-" (for example, :unit corresponds to the line style suboption :line-unit). 



clim-sys:make-lock &optional (lock-name "a CLIM lock'V Function 

Creates a lock whose name is name, name is a string. 

On systems that do not support locking, this will return a new list of one element, 
nil. 

See the section "Locks in CLIM". 

clim:make-modifier-state &rest modifiers Function 
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Given a set of modifier key names, clim:make-modifier-state returns a modifier 
state corresponding to those keys. The returned value is a fixnum. 

The modifier key names may be zero or more of rshift, rcontrol, :meta, rsuper, 

and rhyper. See the section "Gestures and Gesture Names in CLIM". 



climrmake-opacity value Function 

Creates a member of class climropacity whose opacity is value, which is a real 
number in the range from to 1 (inclusive), where is fully transparent and 1 is 
fully opaque. 



clim:make-pane pane-class &rest pane-options Function 

Selects a class that implements the behavior of the abstract pane pane-class and 
constructs a pane of that class. clim:make-pane must be used either within the 
dynamic scope of a call to clim:with-look-and-feel-realization, which is automati- 
cally established within the :pane, rpanes, and rlayouts options of a climrdefine- 
application-frame. 

clim:make-pane passes pane-options to the pane constructor function to be used as 
initargs for the pane. 

See the section "Panes in CLIM". See the section "Using Gadgets in CLIM". 



climrmake-pattern array designs Function 

Creates a pattern design that has (array-dimension 2d-array 0) cells in the verti- 
cal direction and (array-dimension 2d-array 1) cells in the horizontal direction. 

array must be a two-dimensional array of non-negative integers, each of which is 
less than the length of designs, designs must be a sequence of designs. The design 
in cell (ij) of the resulting pattern is the nth. element of designs, if n is the value 
of (aref array i j). For example, array can be a bit-array and designs can be a 
list of two designs, the design drawn for and the one drawn for 1. 

Each cell of a pattern can be regarded as a hole that allows the design in it to 
show through. Each cell might have a different design in it. The portion of the de- 
sign that shows through a hole is the portion on the part of the drawing plane 
where the hole is located. In other words, incorporating a design into a pattern 
does not change its alignment to the drawing plane, and does not apply a coordi- 
nate transformation to the design. Drawing a pattern collects the pieces of designs 
that show through all the holes and draws the pieces where the holes lie on the 
drawing plane. The pattern is completely transparent outside the area defined by 
the array. 

Each cell of a pattern occupies a 1 by 1 square. You can use climrtransform- 
region to scale the pattern to a different cell size and shape, or to rotate the pat- 
tern so that the rectangular cells become diamond-shaped. Applying a coordinate 
transformation to a pattern does not affect the designs that make up the pattern. 
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It only changes the position, size, and shape of the cells' holes, allowing different 
portions of the designs in the cells to show through. Consequently, applying 
clim:make-rectangular-tile to a pattern of nonuniform designs can produce a dif- 
ferent appearance in each tile. The pattern cells' holes are tiled, but the designs 
in the cells are not tiled and a different portion of each of those designs shows 
through in each tile. 

If array or designs is modified after calling climrmake-pattern, the consequences 
are unspecified. 

In the present implementation, patterned designs are not fully supported as a fore- 
ground or background, and the only patterned designs supported as the rink draw- 
ing option are tilings of patterns of colors. In Cloe there is an additional restric- 
tion that the X offset and Y offset of the tiling must be 8. 

The following creates a pattern that consists of a little arrow, which could be used 
as a command-line prompt. 



(defvar xprompt-arrowx 
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(list cl im:+background-ink+ cl im:+foreground-ink+))) 
See the section "Drawing with Designs in CLIM". 



clim:make-pattern-from-bitmap-file pathname &rest args &key (:type rxllj .-designs 
.■format &allow-other-keys Function 

Reads the bitmap file specified by pathname and creates a CLIM pattern object 
from it. The only file type currently supported is :xll, in the two formats rbitmap 
and rpixmap. 

If the bitmap file did not supply colors for use in the image, you must also supply 
a sequence of designs. This has the same format as for climrmake-pattern. For a 
bitmap, you should probably supply the following as the value for the -.designs ar- 
gument: 

(list cl im:+background-ink+ cl im:+foreground-ink+) 

If you use clim:+transparent-ink+ instead of clim:+background-ink+, the result- 
ing pattern will be translucent instead of opaque. 
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The directory SYS : X1 1 ; INCLUDE; BITMAPS; (or its equivalent) usually has a number of 
Xll bitmap files in it. You might want try try calling climrmake-pattern-from- 
bitmap-file on some of the files in this directory. 



clim:make-point x y Function 

Creates and returns a point object whose coordinates are x and y. The point object 
is an instance of clim:standard-point. 



climrmake-polygon point-seq Function 

Makes an object of class climrstandard-polygon consisting of the area contained 
in the boundary that is specified by the segments connecting each of the points in 
point-seq. 

climrmake-polygon* coord-seq Function 

Makes an object of class climrstandard-polygon consisting of the area contained 
in the boundary that is specified by the segments connecting each of the points 
represented by the coordinate pairs in coord-seq. 

climrmake-polyline point-seq &key .-closed Function 

Makes an object of class climrstandard-polyline consisting of the segments con- 
necting each of the points in point-seq. 

If .-closed is t, the segment connecting the first point and the last point is included 
in the polyline. 

climrmake-polyline* coord-seq &key .-closed Function 

Makes an object of class climrstandard-polyline consisting of the segments con- 
necting each of the points represented by the coordinate pairs in coord-seq. 

If .-closed is t, the segment connecting the first point and the last point is included 
in the polyline. 

climrmake-presentation-type-specifier type-name-and-parameters &rest options 

Function 

Given a presentation type name and its parameters type-name-and-parameters and 
some presentation type options, make a new presentation type specifier that in- 
cludes all of the type parameters and options. This is useful for assembling a pre- 
sentation type specifier with options equal to their default values omitted. This is 
useful for climrdefine-presentation-type-abbreviation, but not for the rinherit- 
from clause of climrdefine-presentation-type. 

For example, 
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(cl im: make-presentation-type-specif ier '(integer 1 10) :base 10) 
==> (integer 1 10) 

(cl im: make-presentation-type-specif ier '(integer 1 10) :base 8) 
==> ((integer 1 10) :base 8) 



clim-sys:make-process function &key :name Function 

Creates a process named name. The new process will evaluate the function func- 
tion (that is, function will be its top-level function), name is a string, and function 
is a function of no arguments. 

On systems that do not support multi-processing, clim-sys:make-process will sig- 
nal an error. 

The exact representation of a process object varies from one platform to another. 
clim-sys:processp will return t for any process object returned by clim-sysrmake- 
process. 

See the section "Multi-processing in CLIM". 



climrmake-rectangle min-point max-point Function 

Makes an object of class climrstandard-rectangle whose edges are parallel to the 
coordinate axes. One corner is at min-point and the opposite corner is at 
max-point. 



climrmake-rectangle* min-x min-y max-x max-y Function 

Makes an object of class climrstandard-rectangle whose edges are parallel to the 
coordinate axes. One corner is at (min-x, min-y) and the opposite corner is at (max- 
x, max-y). 

The representation of rectangles in CLIM is chosen to be efficient. CLIM repre- 
sents rectangles by storing the coordinates of two opposing corners of the rectan- 
gle. Because this representation is not sufficient to represent the result of arbi- 
trary transformations of arbitrary rectangles, CLIM is allowed to return a polygon 
as the result of such a transformation. (The most general class of transformations 
that is guaranteed to always turn a rectangle object into another rectangle object 
is the class of transformations that satisfy climrrectilinear-transformation-p.) 



climrmake-rectangular-tile design width height Function 

Creates a design that tiles the specified rectangular portion of design across the 
entire drawing plane. The resulting design repeats with a period of width horizon- 
tally and height vertically. The portion of the argument design that appears in 
each tile is a rectangle whose top-left corner is at (0,0) and whose bottom-right 
corner is at {width, height). 



Page 1575 



The repetition of design is accomplished by applying a coordinate transformation to 
shift design into position for each tile, and then extracting an width by height por- 
tion of that design. 

Applying a coordinate transformation to a rectangular tile does not change the por- 
tion of the argument design that appears in each tile. It can change the period, 
phase, and orientation of the repeated pattern of tiles. 

For example, the following creates several "stipple" tilings that can used as an 
ink to draw filled-in graphics. 

(defun make-stipple (height width patterns) 

(assert (= height (length patterns)) (height patterns) 

"Height should be same as number of patterns supplied") 
(check-type width (integer 0)) 
(cl im: make-rectangular-tile 

(cl im:make-pattern (make-stipple-array height width patterns) 

(vector cl im:+background-ink+ cl im:+foreground-ink+)) 
width height)) 

(defun make-stipple-array (height width patterns) 

(let ((array (make-array (list height width) :element-type 'bit))) 
(let ((h -1)) 

(dolist (pattern patterns) 
(incf h) 
(let ((w width)) 

(dotimes (pos width) 
(decf w) 

(setf (aref array h w) (ldb (byte 1 pos) pattern)))))) 
array)) 

(defvar xtiles-stipplex 

(make-stipple 8 8 '(#b10000000 
#b10000000 
#b01000001 
#b00111110 
#b00001000 
#b00001000 
#b00010100 
#b11100011))) 
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(defvar xhearts-stipplex 

(make-stipple 8 8 '(#b01101100 
#b10010010 
#b10010010 
#b01000100 
#b00101000 
#b00010000 
#b00000000 
#b00000000))) 

(defvar xparquet-stipplex 

(make-stipple 8 8 '(#b10000000 
#b11000001 
#b00100010 
#b00011100 
#b00001000 
#b00010000 
#b00100000 
tfb01 000000))) 

See the section "Drawing with Designs in CLIM". 



clim-sys:make-recursive-lock &optional (lock-name "a recursive CLIM lock'V 

Function 

Creates a recursive lock whose name is name, name is a string. A recursive lock 
differs from an ordinary lock in that a process that already holds the recursive 
lock can call clim-sys:with-recursive-lock-held on the same lock without blocking. 

On systems that do not support locking, this will return a new list of one element, 
nil. 

See the section "Locks in CLIM". 



climrmake-reflection-transformation point-1 point-2 Function 

Makes a transformation that reflects every point through the line passing through 
the points point-1 and point-2. 



climrmake-reflection-transformation* xl yl x2 y2 Function 

Makes a transformation that reflects every point through the line passing through 
the points (xl, yl) and (x2, y2). 

A reflection is a transformation that preserves lengths and magnitudes of angles, 
but changes the sign (or "handedness") of angles. If you think of the drawing 
plane on a transparent sheet of paper, a reflection is a transformation that "turns 
the paper over". 
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climrmake-rotation-transformation angle &optional origin Function 

Makes a transformation that rotates all points clockwise by angle around the point 
origin. The angle is specified in radians. If origin is supplied it must be a point; if 
not supplied it defaults to (0,0). 



climrmake-rotation-transformation* angle origin-x origin-y Function 

Makes a transformation that rotates all points clockwise by angle around the point, 
{origin-x, origin-y). The angle is specified in radians. 

A rotation is a transformation that preserves length and angles of all geometric 
entities. Rotations also preserve one point and the distance of all entities from that 
point. 



climrmake-scaling-transformation mx my &optional origin Function 

Makes a transformation that multiplies the X-coordinate distance of every point 
from origin by mx and the Y-coordinate distance of every point from origin by my. 
If origin is supplied it must be a point; if not supplied it defaults to (0,0). 



climrmake-scaling-transformation* mx my origin-x origin-y Function 

Makes a transformation that multiplies the X-coordinate distance of every point 
from origin-x by mx and the Y-coordinate distance of every point from origin-y by 
my. 

There is no single definition of a scaling transformation. Transformations that pre- 
serve all angles and multiply all lengths by the same factor (preserving the 
"shape" of all entities) are certainly scaling transformations. However, scaling is 
also used to refer to transformations that scale distances in the X-direction by one 
amount and distances in the Y-direction by another amount. 



clim:make-space-requirement &key (:width 0) (:min-width width) (:max-width 
width) (.-height 0) (:min-height height) (:max-height height) Function 

Constructs and returns a space requirement object having the given components. 
The space requirement object will generally be used to indicate the preferred sizes 
for a pane. 

.-width specifies the preferred width of the pane, and .-height specifies the preferred 
height. 

:min-width specifies that minimum size a pane can take, and :min-height specifies 
the minimum height. 

:max-width specifies the maximum width a pane can take, and :max-height specifies 
the maximum height. If the maximum width or height is clim:+fill+, the pane may 
stretch to fill the available space in that direction. 
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climrmake-stencil array Function 

Creates a pattern design that has (array-dimension array 0) cells vertically and 
(array-dimension array 1) cells horizontally, array must be a two-dimensional ar- 
ray of real numbers between and 1. The design in cell (ij) of the resulting pat- 
tern is the value of the following: 

(cl im: make-opacity (aref array i j)) 

The stencil opacity of the result at a given point in the drawing plane depends on 
which cell that point falls in. If the point is in cell (ij), the stencil opacity is (aref 
array i j). The stencil opacity is outside the region defined by the array. 

Each cell of a pattern occupies a 1 x 1 square. The entity protocol can be used to 
scale the pattern to a different cell size and shape, or to rotate the pattern so that 
the rectangular cells become diamond-shaped. 

If array is modified after calling climrmake-stencil, the consequences are unspeci- 
fied. 



clim:make-text-style family face size Function 

Creates a text style object with the supplied characteristics. Generally, there is no 
need to call clim:make-text-style; you should use clim:parse-text-style or 
clim:merge-text-styles instead. 

family One of :fix, rserif, :sans-serif, or nil. 

face One of rroman, :bold, ritalic, (:bold ritalic), or nil. 

size One of the logical sizes (:tiny, :very-small, :small, mormal, 

rlarge, :very-large, :huge, rsmaller, rlarger), or a real number 
representing the size in printer's points, or nil. 

For example, 

(cl im:with-text-style 

(my-stream (cl im: make-text-style :fix :bold : large)) 
(write-string my-stream "Here is a text-style example.")) 

=> Here is a text-style example. 

A text style object is called fully specified if each of its components has a non-nil 
value, and the size component is not a relative size (that is, is neither rsmaller 
nor rlarger). 

You can use climrtext-style-family, climrtext-style-face, and climrtext-style-size to 

extract components from a text style object. 

See the section "Text Styles in CLIM". 



climrmake-transformation mxx mxy myx myy tx ty Function 

Makes a general transformation whose effect is, 
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x' = m xx x + m xy y + t x 

y' = m yx x + m yy y + t y 

where x and y are the coordinates of a point before the transformation and x' and 
y' are the coordinates of the corresponding point after. 



climrmake-translation-transformation delta-x delta-y Function 

Makes a transformation that translates all points by delta-x in the X direction and 
delta-y in the Y direction. 

A translation is a transformation that preserves length, angle, and orientation of 
all geometric entities. 



clim:map-over-command-table-commands function command-table &key (.-inherited 
t) Function 

Applies function to all of the commands accessible in command-table, function is a 
function that takes a single argument, the command name. 

If .-inherited is nil instead of t, this applies function only to those commands 
present in command-table, that is, it does not map over any inherited command 
tables. 



clim:map-over-command-table-keystrokes function command-table Function 

Applies function to all of the keystroke accelerators in command-table's accelerator 
table, function is a function of three arguments, the menu name (which will be nil 
if there is none), the keystroke accelerator, and the menu item. 

clim:map-over-command-table-keystrokes does not descend into sub-menus. If 
you require this behavior, you should examine the type of the menu item to see if 
it is menu. 



clim:map-over-command-table-menu-items function command-table Function 

Applies function to all of the menu items in command-table's menu, function is a 
function of three arguments, the menu name, the keystroke accelerator (which will 
be nil if there is none), and the menu item. The menu items are mapped in the 
order specified by clim:add-menu-item-to-command-table. 

clim:map-over-command-table-menu-items does not descend into sub-menus. If 
you require this behavior, you should examine the type of the menu item to see if 
it is :menu and make the recursive call from function. 



clim:map-over-command-table-names function command-table &key (.-inherited t) 

Function 
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Applies function to all of the command-line names accessible in command-table, 
function is a function of two arguments, the command-line name and the command 
name. 

If .-inherited is nil instead of t, this applies function only to those command-line 
names present in command-table, that is, it does not map over any inherited com- 
mand tables. 



clim:map-over-frames function &key sport .-frame-manager Generic Function 

Applies function to all of the application frames that "match" .-port and .-frame- 
manager. If .-frame-manager is supplied, only those frames that use that frame 
manager match. If .-port is supplied, only those frames that use that port match. If 
neither .-port nor .-frame-manager is supplied, clim:map-over-frames will call func- 
tion on all of the existing application frames. 

function is a function of one argument, the frame. 

clim:map-over-output-records function record &optional (x-offset 0) (y-offset 0) 
&rest continuation-args Function 

Applies function to all of the child output records in the output record record. 
Normally, function is called with a single argument, an output record. If continua- 
tion-args are supplied, they are passed to function as well. 

x-offset and y-offset are output record offsets that are necessitated by CLIM's repre- 
sentation of output records. In a later release of CLIM, the representation of out- 
put records may change in such a way that the x-offset and y-offset arguments are 
removed. 



clim:map-over-output-records-containing-position function record x y &optional 
x-offset y-offset &rest continuation-args Generic Function 

Applies function to all of the child output records in the output record record that 
overlap the point (x,y). Normally, function is called with a single argument, an out- 
put record. If continuation-args are supplied, they are passed to function as well. 

x-offset and y-offset are output record offsets that are necessitated by CLIM's repre- 
sentation of output records. In a later release of CLIM, the representation of out- 
put records may change in such a way that the x-offset and y-offset arguments are 
removed. 

When clim:map-over-output-records-containing-position maps over the children 
in the record, it does so in such a way that, when it maps over overlapping chil- 
dren, the bottommost (least recently inserted) child is hit last. This is because this 
function is used for things like locating the presentation under the pointer, where 
the topmost child should be the one that is found. 

Any class that is a subclass of climroutput-record must implement this method. 

See the section "Output Recording in CLIM". 
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clim:map-over-output-records-overlapping-region function record region &optional 
x-offset y -offset &rest continuation-args Generic Function 

Applies function to all of the child output records in the output record record that 
overlap the region region. Normally, function is called with a single argument, an 
output record. If continuation-args are supplied, they are passed to function as well. 

x-offset and y-offset are output record offsets that are necessitated by CLIM's repre- 
sentation of output records. In a later release of CLIM, the representation of out- 
put records may change in such a way that the x-offset and y-offset arguments are 
removed. 

When clim:map-over-output-records-overlapping-region maps over the children 
in the record, it does so in such a way that, when it maps over overlapping chil- 
dren, the topmost (most recently inserted) child is hit last. This is because this 
function is used for things such as replaying, where the most recently drawn thing 
must come out on top (that is, must be drawn last). 

Any class that is a subclass of climroutput-record must implement this method. 

See the section "Output Recording in CLIM". 



clim:map-over-polygon-coordinates function polygon Generic Function 

Applies function to all of the coordinates of the vertices of polygon. The function 
takes two arguments, the X and Y coordinates. 



clim:map-over-polygon-segments function polygon Generic Function 

Applies function to the line segments that compose polygon. The function takes 
four arguments, the X and Y coordinates of the start of the line segment, and the 
X and Y coordinates of the end of the line segment. 

When clim:map-over-polygon-segments is called on a closed polyline, it will call 
function on the line segment that connects the last point back to the first point. 



clim:map-over-ports function Generic Function 

Applies function to all of the current ports, function is a function of one argument. 

clim:map-over-region-set-regions function region &key .-normalize Generic Function 

Calls function on each region in region. This is often more efficient than calling 
clim:region-set-regions. region can be either a clim:region-set or any member of 
climrregion, in which case function is called once on region itself. 

■.normalize can be either :x-banding or :y-banding, and is interpreted as it is for 
clim:region-set-regions. 

clim:map-over-sheets function sheet Generic Function 
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Applies function to sheet, and then applies function to all of the descendants (the 
children, the children's children, and so forth) of sheet, function is a function of 
one argument, the sheet. 



clim:map-over-sheets-containing-position function sheet x y Generic Function 

Applies function to all of the children of sheet containing the position (x,y). x and y 
are expressed in sheet's coordinate system. 

function is a function of one argument, the sheet. 



clim:map-over-sheets-overlapping-region function sheet region Generic Function 

Applies function to all of the children of sheet overlapping the region region, region 
is expressed in sheet's coordinate system. 

function is a function of one argument, the sheet. 



clim-sys:map-resource function resource Function 

Calls function once on each object in the resource named name, function is a func- 
tion of three arguments, the object, a boolean value that is t if the object is in use 
or nil if it is free, and name. 

See the section "Resources in CLIM". 



clim:map-sheet-position-to-parent sheet x y Function 

Applies sheet's, transformation to the point (x,y), returning the coordinates of that 
point in sheet's parent's coordinate system. 

See the section "Sheet Geometry Protocols". 



clim:map-sheet-position-to-child sheet x y Function 

Applies the inverse of sheet's transformation to the point (x,y) (represented in 
sheet's parent's coordinate system), returning the coordinates of that same point in 
sheet's coordinate system. 

See the section "Sheet Geometry Protocols". 



climrmedium Class 

The protocol class that corresponds to a medium. If you want to create a new class 
that obeys the medium protocol, it must be a subclass of climrmedium. 



climrmedium-background medium Generic Function 
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Returns the current background design of the medium. You can use setf on 
climrmedium-background to change the background design. You must not set the 
background ink to an indirect ink. 

For background information and related operations, see the section "Components of 
CLIM Mediums". 



climrmedium-clipping-region medium Generic Function 

Returns the current clipping region of the medium. You can use setf on 
climrmedium-clipping-region to change the clipping region. 

In the current implementation of CLIM, the clipping region must be either a rect- 
angle or a rectangle set. 

For background information and related operations, see the section "Components of 
CLIM Mediums". 



clim:medium-default-text-style medium Generic Function 

The default text style for medium. clim:medium-default-text-style must be a fully 
specified text style, unlike clim:medium-text-style which can have null compo- 
nents. Any text styles that are not fully specified by the time they are used for 
rendering are merged against clim:medium-default-text-style using climrmerge- 
text-styles. 

You can use setf on clim:medium-default-text-style to change the default text 
style, but the text style must be a fully specified text style. 

See the section "Text Styles in CLIM". 



clim:medium-draw-ellipse* medium center-x center-y radius-1-dx radius-1-dy radius- 
2-dx radius-2-dy start-angle end-angle filled Generic Function 

Draws an ellipse on the medium medium. The center of the ellipse is at (x,y), and 
the radii are specified by the two vectors (radius- l-dx,radius-l-dy) and (radius-2- 
dx,radius-2-dy) . The center point and radii are transformed by the medium's cur- 
rent transformation. 

start-angle and end-angle are real numbers that specify an arc rather than a com- 
plete ellipse. The medium transformation must be applied to the angles as well. 

If filled is t, the ellipse is filled, otherwise it is not. 

The ink, clipping region, and line style are gotten from the medium. See the sec- 
tion "The CLIM Drawing Environment". 



clim:medium-draw-line* medium xl yl x2 y2 Generic Function 

Draws a line on the medium medium. The line is drawn from (xl,yl) to (x2,y2), 
with the start and end positions transformed by the medium's current transforma- 
tion. 
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The ink, clipping region, and line style are gotten from the medium. See the sec- 
tion "The CLIM Drawing Environment". 



clim:medium-draw-lines* medium position-seq Generic Function 

Draws a set of disconnected lines on the medium medium, position-seq is a se- 
quence of coordinate pairs, which are real numbers. It is an error if the length of 
position-seq is not evenly divisible by 4. The coordinates in position-seq are trans- 
formed by the medium's current transformation. 

The ink, clipping region, and line style are gotten from the medium. See the sec- 
tion "The CLIM Drawing Environment". 



clim:medium-draw-point* medium x y Generic Function 

Draws a point on the medium medium. The point is drawn at (x,y), transformed by 
the medium's current transformation. 

The ink, clipping region, and line style are gotten from the medium. See the sec- 
tion "The CLIM Drawing Environment". 



clim:medium-draw-points* medium position-seq Generic Function 

Draws a set of points on the medium medium, position-seq is a sequence of coordi- 
nate pairs, which are real numbers. It is an error if position-seq does not contain 
an even number of elements. The coordinates in position-seq are transformed by 
the medium's current transformation. 

The ink, clipping region, and line style are gotten from the medium. See the sec- 
tion "The CLIM Drawing Environment". 



clim:medium-draw-polygon* medium position-seq closed filled Generic Function 

Draws a polygon or polyline on the medium medium, position-seq is a sequence of 
coordinate pairs, which are real numbers. It is an error if position-seq does not 
contain an even number of elements. The coordinates in position-seq are trans- 
formed by the medium's current transformation. 

If filled is t, the polygon is filled, otherwise it is not. If closed is t, the coordinates 
in position-seq are considered to define a closed polygon, otherwise the polygon will 
not be closed. 

The ink, clipping region, and line style are gotten from the medium. See the sec- 
tion "The CLIM Drawing Environment". 



clim:medium-draw-rectangle* medium xl yl x2 y2 filled Generic Function 

Draws a rectangle on the medium medium. The corners of the rectangle are at 
(xl,yl) and (x2,y2), with the corner positions transformed by the medium's current 
transformation. If filled is t, the rectangle is filled, otherwise it is not. 
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The ink, clipping region, and line style are gotten from the medium. See the sec- 
tion "The CLIM Drawing Environment". 



climrmedium-draw-rectangles* medium position-seq filled Generic Function 

Draws a set of rectangles on the medium medium, position-seq is a sequence of co- 
ordinate pairs, which are real numbers. It is an error if the length of position-seq 
is not evenly divisible by 4. The coordinates in position-seq are transformed by the 
medium's current transformation. If filled is t, the rectangle is filled, otherwise it 
is not. 

The ink, clipping region, and line style are gotten from the medium. See the sec- 
tion "The CLIM Drawing Environment". 



climrmedium-draw-text* medium string-or-char x y start end align-x align-y to- 
wards-x towards-y transform-glyphs Generic Function 

Draws a character or a string on the medium medium. The text is drawn starting 
at (x,y), and towards (toward-x,toward-y); these positions are transformed by the 
medium's current transformation. 

The ink, clipping region, and text style are gotten from the medium. See the sec- 
tion "The CLIM Drawing Environment". 



climrmedium-drawable medium Generic Function 

Returns the host window system object (or "drawable") that is drawn on by the 
CLIM drawing functions when they are called on medium. If medium is not associ- 
ated with any sheet, or the sheet with which it is associated is not "mirrored" on 
a display server, this function will return nil. 

When some part of a program must be able to draw on a window with maximum 
speed and portability is less important than performance, you can use 
climrmedium-drawable to get the host window system object and then draw di- 
rectly on that using the host window system's drawing functions. See the macro 
climrwith-medium-state-cached. 



climrmedium-foreground medium Generic Function 

Returns the current foreground design of the medium. You can use setf on 
climrmedium-foreground to change the foreground design. You must not set the 
foreground ink to an indirect ink. 

For background information and related operations, see the section "Components of 
CLIM Mediums". 



climrmedium-ink medium Generic Function 
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Returns the current drawing ink of the medium. You can use setf on 
clim:medium-ink to change the current ink. 

For background information and related operations, see the section "Components of 
CLIM Mediums". 



clim:medium-line-style medium Generic Function 

Returns the current line style of the medium. You can use setf on climrmedium- 
line-style to change the line style. 

For background information and related operations, see the section "Components of 
CLIM Mediums". 



clim:medium-merged-text-style medium Generic Function 

Returns the fully merged text style that will be used when drawing text on medi- 
um. It returns the result of 

(cl im:merge-text-styles (cl im: medium-text-style medium) 

(cl im: medium-default- text-style medium)) 

That is, the components of the current text style that are not nil will replace the 
defaults from medium's default text style. Unlike the preceding clim:medium-text- 
style and clim:medium-default-text-style, clim:medium-merged-text-style is read- 
only. 



clim:medium-sheet medium Generic Function 

Returns the sheet with which the medium medium is associated. See the section 
"Sheet Output Protocols". 



clim:medium-text-style medium Generic Function 

Returns the current text style of the medium. You can use setf on climrmedium- 
text-style to change the current text style. 

For background information and related operations, see the section "Components of 
CLIM Mediums". 



climrmedium-transformation medium Generic Function 

Returns the current transformation of the medium. You can use setf on 
climrmedium-transformation to change the current transformation. 

For background information and related operations, see the section "Components of 
CLIM Mediums". 



climrmediump object Generic Function 
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Returns t if and only if object is of type climrmedium, otherwise returns nil. 



member &rest elements Clim Presentation Type Abbreviation 

The presentation type that specifies one of elements. The options (:name-key, 
rvalue-key, and rpartial-completers) are the same as for climrcompletion. 



climrmember-sequence sequence &key :test Clim Presentation Type Abbreviation 

Like member, except that the set of possibilities is the sequence sequence. The pa- 
rameter :test and the options (:name-key, rvalue-key, and rpartial-completers) are 
the same as for climrcompletion. 



climrmember-alist alist &key :test Clim Presentation Type Abbreviation 

Like member, except that the set of possibilities is the alist alist. Each element of 
alist is either an atom (as in climrmember-sequence) or a list whose car is the 
name of that possibility and whose cdr is one of the following: 

• The value (which must not be a cons) 

• A list of one element, the value 

• A property list containing one or more of the following properties: 

rvalue — the value 

r documentation — a descriptive string 

The :test parameter and the options are the same as for climrcompletion except 
that the rvalue-key and r documentation-key options default to functions that sup- 
port the specified alist format. 



climrmenu-choose items &rest keys &key .-associated-window :text-style .-foreground 
.-background .-default-item .-label .scroll-bars .-printer .-presentation-type .-cache .-unique- 
id :id-test -.cache-value -.cache-test :max-width :max-height :n-rows :n-columns :x- 
spacing :y-spacing :row-wise :cell-align-x :cell-align-y :x-position :y-position .-pointer- 
documentation -.menu-type Function 

Displays a menu with the choices in items. It returns three values: the value of 
the chosen item, the item itself, and the event corresponding to the gesture that 
the user used to select it. items can be a list or a general sequence. 

If possible, climrmenu-choose will use the menu facilities provided by the host 
window system. It is generally possible for CLIM to use the native menu facilities 
when you do not supply any of the arguments that require the menu to be format- 
ted in any special way. 

When enabled by climr*abort-menus-when-buried*, this function returns nil for 
all values if the menu is aborted by burying it. 
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items A sequence of menu items. Each menu item has a visual represen- 
tation derived from a display object, an internal representation 
which is a value object, and a set of menu item options. 

The form of a menu item is one of the following: 



an atom 



a cons 



a list 



The item is both the display object and the val- 
ue object. 

The car is the display object and the cdr is the 
value object. The value object must be an atom. 
If you need to return a list as the value, use the 
rvalue option in the list menu item format de- 
scribed below. 

The car is the display object and the cdr is a 
list of alternating option keywords and values. 
The value object is specified with the keyword 
rvalue and defaults to the display object if 
rvalue is not present. 



The menu item options are: 



rvalue 
r style 

ritems 



Specifies the value object. 

Specifies the text style used to princ the display 
object when neither the .-presentation-type nor 
the sprinter option is specified. 

Specifies an item list for a sub-menu used if 
this item is selected. 



r documentation 

Associates some documentation with the menu 
item. When .-pointer-documentation is not nil, 
this documentation will be used as pointer docu- 
mentation for the item. 

The visual representation of an item depends on the .-printer and 
.-presentation-type keyword arguments. If .-presentation-type is sup- 
plied, the visual representation is produced by climrpresent of the 
menu item with that presentation type. Otherwise, if .-printer is 
supplied, the visual representation is produced by the .-printer func- 
tion which receives two arguments, the item and a stream to write 
on. The .-printer function should output some text or graphics at the 
stream's cursor position, but need not call climrpresent. If neither 
.-presentation-type nor .-printer is supplied, the visual representation 
is produced by princ of the display object. If .-presentation-type or 
.-printer is supplied, the visual representation is produced from the 
entire menu item, not just from the display object. 
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.-associated-window 

The CLIM window with which the menu is associated. This defaults 
to the top-level sheet of the current application frame. You should 
only rarely need to supply this argument. 

■.text-style A text style that defines how the menu items are presented. 

■.foreground and background 

These specify the default foreground and background for the menu. 
These default from the associated window. 

.scroll-bars 

This can be nil, :none, rhorizontal, rvertical, or :both. The default 
is rvertical. 

.-label The string that the menu title will be set to. 

.■printer The function used to print the menu items in the menu. The func- 
tion must take two arguments, the menu item and the stream to 
print it to. The default is a function that displays an ordinary menu 
item. 

.■presentation-type 

Specifies the presentation type of the menu items. The default is 
climrmenu-item. 

:max-width 

Specifies the maximum width of the table display (in device units). 
(Can be overridden by :n-rows.) 

:max-height 

Specifies the maximum height of the table display (in device units). 
(Can be overridden by :n-columns.) 

:n-rows Specifies the number of rows in the menu. 

:n-columns 

Specifies the number of columns in the menu. 

:x-spacing 

Determines the amount of space inserted between columns of the 
table; the default is the width of a space character. :x-spacing can 
be specified in one of the following ways: 

Integer 

A size in the current units to be used for spacing. 

String or character 

The spacing is the width or height of the string or char- 
acter in the current text style. 

Function 

The spacing is the amount of horizontal or vertical space 
the function would consume when called on the stream. 
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List of form (number unit) 

The unit is rpoint, rpixel, or rcharacter. 

.y-spacing 

Specifies the amount of blank space inserted between rows of the 
table; the default is the vertical spacing for the stream. The possi- 
ble values for this option are the same as for the :x-spacing option. 

:cell-align-x 

Specifies the horizontal placement of the contents of the cell. Can 
be one of: :left, rright, or reenter. The default is rleft. 

:cell-align-y 

Specifies the vertical placement of the contents of the cell. Can be 
one of: :top, rbottom, or reenter. The default is :top. 

.■pointer-documentation 

Either nil (the default), meaning the no pointer documentation 
should be computed, or a stream on which pointer documentation 
should be displayed. 

:x-position and :y-position 

These can be supplied to position the menu. If the are not supplied, 
the menu will be positioned near the pointer. 

■.default-item 

The menu item over which the mouse will appear. 

-.cache Indicates whether CLIM should cache this menu for later use. If t, 
then :unique-id and :id-test serve to uniquely identify this menu. 
Caching menus can speed up later uses of the same menu. The de- 
fault is nil. 

:unique-idlf -.cache is non-nil, this is used to identify the menu. It defaults to 
the items, but can be set to a more efficient tag. 

:id-test The function that compares unique-ids. Defaults to equal. 

■.cache-value 

If -.cache is non-nil, this is the value that is compared to see if the 
cached menu is still valid. It defaults to items, but you may be able 
to supply a more efficient cache value than that. 

■.cache-test The function that compares cache-values. Defaults to equal. 
See the section "Examples of Menus and Dialogs in CLIM". 



clinirnienu-choose-froni-drawer menu type drawer &key :x-position :y-position 
.-cache -.unique-id (:id-test #'equal) (-.cache-value t) (-.cache-test #'eql) :leave-menu- 
visible .-default-presentation Function 

A lower-level routine for displaying menus that allows you much more flexibility in 
the menu layout. Unlike climrmenu-choose, which automatically creates and lays 



Page 1591 



out the menu, clim:menu-choose-from-drawer takes a programmer-provided win- 
dow and drawing function. Then it draws the menu items into that window using 
the drawing function. The drawing function gets called with arguments (stream 
type). It can use type for its own purposes, the usual being to use it in a call to 
climrpresent. 

clim:menu-choose-from-drawer returns two values; the object the user clicked on, 
and the gesture. 

You can create a temporary window for drawing their menu using clim:with-menu. 

When enabled by clim:*abort-menus-when-buried*, this function returns nil for 
all values if the menu is aborted by burying it. 

menu The CLIM window to use for the menu. 

type The presentation type of the mouse-sensitive items in the menu. 

This is the input context that will be established once the menu is 
displayed. For users who don't need to define their own types, a 
useful presentation-type is clim:menu-item. 

drawer A function that takes arguments (stream type) that draws the con- 
tents of the menu. 

:x-positionThe requested left edge of the menu (if supplied). 

:y-position 

The requested top edge of the menu (if supplied). 

:leave-menu-visible 

If non-nil, the window will not be deexposed once the selection has 
been made. The default is nil, meaning that the window will be de- 
exposed once the selcetion has been made. 

: default-presentation 

Identifies the presentation that the mouse is pointing to when the 
menu comes up. 

.-cache, :unique-id, :id-test, xache-value, and xache-test are as for climrmenu-choose. 
See the section "Examples of Menus and Dialogs in CLIM". 



clim:menu-choose-command-from-command-table command-table &key (associat- 
ed-window (clim:frame-top-level-window climr*application-frame*)J :text-style .-la- 
bel .-cache (:unique-id climrcommand-tablej (:id-test #'eql) xache-value (xache-test 
#'eql) Function 

Displays a menu of all of the commands in command-table's, menu, and waits for 
the user to choose one of the commands. The returned value is a command object. 
clim:menu-choose-command-from-command-table can invoke itself recursively if 
there are sub-menus. 

.-associated-window, -.text-style, -.label, xache, :unique-id, :id-test, xache-value, and 
xache-test are as for climrmenu-choose. 
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climrmenu-command-parser command-table stream &key .-timeout Function 

Reads a command on behalf of an application frame's command loop by soliciting 
input via command menus. User programs should not call this function explicitly, 
but should rather bind clim:*command-parser* to it. 

This is the function CLIM uses to parse commands in a menu driven interface. 



clim:menu-read-remaining-arguments-for-partial-command partial-command com- 
mand-table stream start-location &key :for-accelerator Function 

Reads the remaining arguments of a partially filled-in command on behalf of an 
application frame's command loop by getting input via the mouse. User programs 
should not call this function explicitly, but should rather bind clim:*partial- 
command-parser* to it. 



clim:merge-text-styles stylel style2 Generic Function 

Merges stylel against the defaults provided by style2. That is, any nil components 
in stylel are filled in from style2. 

If the size component of stylel is a relative size, the resulting size will be the size 
component of style2 as modified by the relative size. 

If the face component of stylel is :bold and the face component of style2 is ritalic 
(or vice-versa), the resulting face will be (:bold ritalic). 

Here are some examples of text style merging. 

(cl im:merge-text-styles '(:fix :bold 12) '(nil : roman nil)) 

=> #<STANDARD-TEXT-STYLE : FIX. : BOLD. 12 1116707341> 

(cl im:merge-text-styles '(:fix :bold nil) '(nil : roman 10)) 

=> #<STANDARD-TEXT-STYLE : FIX. : BOLD. 10 1116707675> 

(cl im:merge-text-styles '(:fix :bold 12) '(nil :italic 10)) 

=> #<STANDARD-TEXT-STYLE :FIX.(:B0LD : ITALIC) . 12 1116707454> 

See the section "Text Styles in CLIM". 



clim:+meta-key+ Constant 

The modifier state bit that corresponds to the user holding down the meta key on 
the keyboard. See the section "Operators for Gestures in CLIM". 



clim:modifier-state-matches-gesture-name-p state gesture-name Function 

Returns t if the modifier state state "matches" the modifier state of the gesture 
named by gesture-name, state is an integer such as is returned by climrmake- 
modifier-state. 
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clim:move-sheet sheet x y Generic Function 

Moves sheet to the new position (x,y). x and y are in coordinates relative to sheet's 
parent. 

clim:move-sheet works by modifying the sheet's transformation, and could be im- 
plemented as follows: 

(defmethod cl im: move-sheet 

((sheet cl im: basic-sheet) x y) 
(let ((transform (cl im: sheet-transformation sheet))) 
(multiple-value-bind (old-x old-y) 

(cl im: transform-position transform 0) 
(setf (cl im:sheet-transformation sheet) 

(cl im : compose- t r ansl at ion-with- transformation 
transform (- x old-x) (- y old-y)))))) 

You should not generally use this function to move a sheet, because it does not in- 
teract directly with the frame layout protocol. That is, moving a sheet with 
clim:move-sheet may appear not to have any effect until you invoke the entire lay- 
out protocol. If you need to move a top-level sheet, use clim:position-sheet- 
carefully. 

clim:move-and-resize-sheet sheet x y width height Generic Function 

Moves sheet to the new position (x,y), and simultaneously changes the size of the 
sheet to have width width and height height, x and y are in coordinates relative to 
sheet's, parent. 

clim:move-and-resize-sheet could be implemented as follows: 

(defmethod cl im:move-and-resize-sheet 

((sheet cl im:basic-sheet) x y width height) 
(cl im:move-sheet sheet x y) 
(cl im: resize-sheet sheet width height)) 

You should not generally use this function to move or resize a sheet, because it 
does not interact directly with the frame layout protocol. That is, moving and re- 
sizing a sheet with clim:move-and-resize-sheet may appear not to have any effect 
until you invoke the entire layout protocol. If you need to move and resize a top- 
level sheet, use clim:position-sheet-carefully and clim:size-frame-from-contents. 



clim-sys:*multiprocessing-p* Variable 

The value of this variable is t if the current Lisp environment supports multi- 
processing, otherwise it is nil. 



clim:new-page stream Generic Function 

When called on a PostScript output stream, this causes a PostScript "newpage" 
command to be included in the output at the point clim:new-page is called. 
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The exact effect of clim:new-page is undefined if you specified either :multi-page 
t or : scale-to-fit t to clim:with-output-to-postscript-stream. 

See the section "Hardcopy Streams in CLIM". 



climrnote-gadget-activated client gadget Generic Function 

This function is invoked after a gadget is made active. You can specialize this 
generic function on the client or gadget in order to modify the behavior when the 
gadget is activated. 



climrnote-gadget-deactivated client gadget Generic Function 

This function is invoked after a gadget is made inactive. You can specialize this 
generic function on the client or gadget in order to modify the behavior when the 
gadget is deactivated. 



climrnote-progress numerator &optional (denominator I) (note clim:*current- 
progress-note*) Function 

Notes the progress of an operation by updating the progress bar. This function is 
only used in the body of the climrnoting-progress macro. The progress bar is up- 
dated by fractional amounts between and 1. 

numerator is the numerator of the fraction by which to update the bar. denomina- 
tor is the denominator of the fraction by which to update the bar; the default is 1. 

note-var is a variable bound to the current note object; the default is 
clim: *current-progress-note* . 

(cl im:noting-progress ("Working Away By Tenths") 
(loop for i from 0.1 to 1.0 by 0.1 do 
(tv: note-progress i) 
(sleep 1))) 



clim:note-sheet-region-changed sheet Generic Function 

This function is invoked whenever the region of sheet is changed. See the section 
"Sheet Geometry Protocols". 



clim:note-sheet-transformation-changed sheet Generic Function 

This function is invoked whenever the transformation of sheet is changed. See the 
section "Sheet Geometry Protocols". 



climrnote-viewport-position-changed frame pane x y Generic Function 
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CLIM calls this function whenever a pane gets scrolled, whether it is scrolled pro- 
grammatically (by clim:window-set-viewport-position, for example) or by a user 
gesture (such as clicking on a scroll bar). 

pane is that pane that was scrolled, frame is the frame in which the pane resides, 
and x and y are the new viewport position. 

You can specialized this function when you want to extend the scrolling behavior 
of a pane. This might be used to "link" to panes together, so that when one pane 
is scrolled, the other pane gets scrolled as well. If you want to implement com- 
pletely new scrolling behavior for a sheet, you should specialize climrscroll-extent 
instead. 



clim:notify-user frame message &key .-associated-window .-title -.exit-boxes -.text-style 
-.foreground -.background :x-position :y-position Generic Function 

Notifies the user of some event on behalf of the application frame frame, message 
is a message string, .-associated-window is the window with which the notification 
is associated, .-title is a string used to label the notification, -.exit-boxes is as for 
climraccepting-values. 

-.text-style, -.foreground, and -.background are the text style, foreground ink, and 
background ink to use in the notification window. :x-position and :y-position can be 
supplied to position the notification window. 

On Genera, this pops up a small dialog box containing the message. On other 
platforms, this may use an alert box or the equivalent. 



climrnoting-progress (stream name &optional note-var) &body body Macro 

Binds the dynamic environment such that the progress of an operation performed 
within the body of the macro is noted by a progress bar displayed in the specified 
stream (such as the pointer documentation pane). The function climrnote-progress 
does the updating of the progress bar. 

name is a string naming the operation being noted; this string is displayed with 
the progress bar. 

note-var is a variable bound to the current note object; the default is 
clim: *current-progress-note* . 

(cl im:noting-progress ("Working Away By Tenths") 
(loop for i from 0.1 to 1.0 by 0.1 do 
(tv: note-progress i) 
(sleep 1))) 



clim:+nowhere+ Constant 

The empty region (the opposite of clim:+everywhere+). 
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null Clim Presentation Type 

The presentation type that represents "nothing". The single object associated with 
this type is nil, and its printed representation is "None". 



clim:null-or-type type Clim Presentation Type Abbreviation 

A compound type that is used to select nil, whose printed representation is the 
special token "None", or an object of type type. 

type can be a presentation type abbreviation. 



clim:*null-presentation* Constant 

The "null" presentation, which occupies any part of a window where there are no 
presentations matching the current input context. The presentation type of this ob- 
ject is clim:blank-area. 



number Clim Presentation Type 

The presentation type that represents a general number. It is the supertype of all 
the number types. 



clim:*numeric-argument-marker* Variable 

If you are building a command object that has numeric arguments that have not 
yet been supplied (for example, a numeric argument gotten from a keystroke ac- 
celerator), CLIM uses the value of clim:*numeric-argument-marker* as a place- 
holder for those arguments. The command processor will fill in the places so 
marked by inserting the value of the input editor's accumulated numeric argu- 
ment. 

The following might come from a debugger. When the user types control -5 con- 
trol -N, the debugger will move "down" five frames in the stack. 

(def ine-debugger-command (com-next-f rame :name t) 
(&key (n-frames '((integer) :base 10) 
:default 1 

: documentation "Move this many frames") 
(detailed 'boolean 

:default nil :mentioned-defaul t t 

: documentation "Show locals and disassembled code")) 
"Show the next frame in the stack" 
(cond ((and (plusp n-frames) 

(bottom-f rame-p (current-frame cl im:*appl ication-f rame*))) 
(format t "~&You are already at the bottom of the stack.")) 
(t 
(show-frame (nth-frame n-frames) :detailed detailed)))) 
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(cl im : add-keystroke-to-command-tabl e 
'debugger '(:n : control) : command 
1 (com-next-f rame :n-frames ,cl im:xnumeric-argument-markerx)) 



climropacity Class 

A member of the class climropacity is a completely colorless design that is typical- 
ly used as the second argument to clim:compose-in to adjust the opacity of anoth- 
er design. 



climropacity-value opacity Generic Function 

Returns the value of opacity, which is a real number in the range from to 1 
(inclusive). 



climropacityp object Generic Function 

Returns t if and only if object is of type climropacity. 

clim:open-stream-p stream Generic Function 

In CLIM, open-stream-p is defined as a generic function. Otherwise, it behaves 
the same as the normal Common Lisp open-stream-p function. 



climropen-window-stream &key sport .-frame-manager deft stop .-right .-bottom .-width 
.-height .-foreground .-background .-text-style (.-vertical-spacing 2) (:end-of-line-action 
rallowj (:end-of-page-action rallowj .-output-record (-.draw t) (.-record t) (dnitial-cursor- 
visibility roff) -.text-margin : default-text-mar gin .save-under .-input-buffer (scroll-bars 
rvertical) .-borders .-label Function 

climropen-window-stream is a convenient interface for creating a CLIM window 
outside of an application frame. This function is not used often. Instead, you will 
usually use windows that are created by an application frame or by the menu and 
dialog functions. 

Note that some of these keyword arguments are also available as pane options in 
climrdefine-application-frame. 

.-port, .-frame-manager 

The port or frame manager on which to create the window. 
You must supply one of these two arguments. 

.-left, stop, .-right, .-bottom, .-width, .-height 

Position and shape of the window within its parent, in device 
units. The default is locate the window at (0,0) and to fill the 
entire parent. 
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.-foreground, .-background, -.text-style, -.draw, -.record, :end-of -line-action, :end-of-page- 
action, .-text-margin 
Initial values for the corresponding stream attributes. 

: default-text-mar gin Text margin to use if clim:stream-text-margin isn't set. This 
defaults to the width of the viewport. 

.-borders Controls whether borders are drawn around the window (t or 

nil). The default is t. 

dnitial-cursor-visibility 

:off (the default) means make the cursor visible if the window 
is waiting for input. :on means make it visible all the time, nil 
means the cursor is never visible. 

-.label nil or a string label for the window. The default is nil for no 

label. 

-.output-record Specify this if you want a different output history mechanism 

than the default. 

-.scroll-bars Indicates whether the new window should have scroll bars. One 

of nil, :none, rvertical, rhorizontal, or :both. The default is 
:both. 

.-vertical-spacing Amount of extra space between text lines, in device units. 

.-input-buffer The event queue to use for this window. 

The remaining keyword arguments are internal and should not be used. 

You can use clim:position-sheet-carefully and clim:size-frame-from-contents to 

set the size and position of windows created using climropen-window-stream. 



clim:option-pane Class 

The clim:option-pane gadget class corresponds to an option pane, that is, a pane 
whose semantics are identical to a list pane, but whose visual appearance is a sin- 
gle push button which, when pressed, pops up a menu of selections. It is a sub- 
class of climrvalue-gadget. 

See the section "Using Gadgets in CLIM". 

In addition to the initargs for climrvalue-gadget and the usual pane initargs 
(rforeground, rbackground, rtext-style, space requirement options, and so forth), 
the following initargs are supported: 

rmode Either :one-of or :some-of. When it is :one-of, the option pane acts 
like a radio box, that is, only a single item can be selected. Other- 
wise, the option pane acts like a check box, in that zero or more 
items can be selected. The default is :one-of. 

ritems A list of items. 
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:name-key 

A function of one argument that generate the name of an item from 
the item. The default is princ-to-string. 

rvalue-key 

A function of one argument that generate the value of an item from 
the item. The default is identity. 

rtest A function of two arguments that compares two items. The default 

is eql. 

Calling climrgadget-value on an option pane will return the single selected item 
when the mode is :one-of, or a sequence of selected items when the mode is 
:some-of. 

The climrvalue-changed-callback is invoked when the select item (or items) is 
changed. 

Here are some examples of option panes: 

(cl im: make-pane 'cl im: option-pane 
: label "Select a vendor" 
:value "Symbolics" 
:test 'string= 

: val ue-changed-cal 1 back ' opti on-pane-changed-cal 1 back 
litems '("Franz" "Lucid" "Harlequin" "Symbolics")) 

(cl im: make-pane 'cl im: option-pane 
: label "Select some languages" 
: value ' ("Lisp" "C++") 
:mode :some-of 

: val ue-changed-cal 1 back ' opti on-pane-changed-cal 1 back 
: items '("Lisp" "Fortran" "C" "C++" "Cobol" "Ada")) 

(defun opti on-pane-changed-cal 1 back (tf value) 

(format t "~&0ption menu ~A changed to ~S" tf value)) 



clim:option-pane-view Class 

The class that represents the view corresponding to an option pane. Options panes 
are another way of representing "one of" or "some of" fields. 



clim:+option-pane-view+ Constant 

An instance of the class clim:option-pane-view. 

or &rest types Clim Presentation Type 

The presentation type that is used to specify one of several types, for example, 
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(or (member : al 1 :none) integer) 

climraccept returns one of the possible types as its second value, not the original 
or presentation type specifier. 

The elements of types can be presentation type abbreviations. 

The climraccept method for the or type works by iteratively calling climraccept 
on each of the presentation types in types. It establishes a condition handler for 
userrrparse-error, calls climraccept, and returns the result if no condition is sig- 
nalled. If a userrrparse-error condition is signalled, CLIM calls the climraccept 
method for the next type. If all of the calls to climraccept fail, the climraccept 
method for or signals a userrrparse-error. 



climroriented-gadget-mixin Class 

The class that is mixed in to a gadget that has an orientation associated with it, 
for example, a slider. 

All subclasses of climroriented-gadget-mixin must handle the rorientation initarg, 
which is used to specify the orientation of the gadget. 



climroutlining f&rest options &key .-thickness &allow-other-keys) &body contents 

Macro 

The climroutlining layout macro puts an outlined border of the specified thickness 
around a single child pane, .-thickness is the thickness in device units, contents is a 
form that produces a single pane. 

The climroutlining macro is the usual way of creating a pane of type 
climroutlined-pane. 

options may include other pane initargs, such as space requirement options, 
rforeground, rbackground, rtext-style, and so forth. 



climroutlined-pane Class 

The layout pane class that draws a border around its child pane, climroutlining 
generates a pane of this type. 

In addition to the usual sheet initargs (the space requirement initargs, 
rforeground and rbackground), this class supports two other initargs: 

rthickness 

An integer that specifies the thickness of the border, in device 
units. 

rcontents The pane that will be the child. 



climroutput-record Class 
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The protocol class that is used to indicate that an object is an output record, that 
is, a CLIM object that contains other output records. If you want to create a new 
class the obeys the output record protocol, it must be a subclass of climroutput- 
record. 

If you think of output records being arranged in a tree, output records are the 
non-leaf nodes of the tree. 

See the section "Output Recording in CLIM". 



clim:output-record-count record Generic Function 

Returns the number of output records that are children of record. 

climroutput-record-children record Function 

Returns a sequence of output records that are the children of the output record 
record. If record has no children, this will return nil. 

For some classes of output records, this function may create a new sequence hold- 
ing the child output records. Because of this, you should use clim:map-over- 
output-records instead of this, if it is possible to do so. 

See the section "Output Recording in CLIM". 

clim:output-record-p object Function 

Returns t if and only object is of type climroutput-record. 

climroutput-record-parent record Generic Function 

Returns the output record that it the parent of record. If record has no parent, 
climroutput-record-parent will return nil. 

See the section "Output Recording in CLIM". 

climroutput-record-position record Generic Function 

Returns the X and Y position of record as two real numbers. The position of an 
output record is the position of the upper-left corner of its bounding rectangle. 
The position is relative to the output record's parent, where (0,0) is the upper-left 
corner of the parent output record. 

See the section "Output Recording in CLIM". See the function clinirconvert-from- 
relative-to-absolute-coordinates. 

clim:output-record-refined-position-test record x y Generic Function 
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CLIM uses clim:output-record-refined-position-test to definitively determine that 
the point (x,y) is contained within the output record record. Once the position (x,y) 
has been determined to lie within the bounding rectangle of the record, CLIM calls 
clim:output-record-refined-position-test. 

You can define methods for this generic function for your own output record class- 
es in order to provide a more precise definition of a hit. For example, output 
records for ellipses implement a method that detects whether the pointer cursor is 
within the ellipse. 

The following example shows how you might implement this method for an output 
record that records a filled-in circle: 

(def method cl im:output-record-ref ined-posit ion- test 
((record circle-output-record) x y) 
(with-slots (center-x center-y radius) record 

(point-inside-ci rcle-p (- x center-x) (- y center-y) radius))) 



clim:output-record-set-position record x y Generic Function 

Changes the position of the output record record to the new position x and y. x 
and y are the new left and top coordinates of the record. The position is relative 

to the output record's parent, where (0,0) is the upper-left corner of the parent 
output record. 

See the section "Output Recording in CLIM". See the function clim:convert-from- 
absolute-to-relative-coordinates. 



clim:output-recording-stream-p object Function 

Returns t if and only if object is an output recording stream. 

clim:output-stream-p stream Generic Function 

Returns t if stream is a CLIM output stream, otherwise returns nil. 

clim:palette-color-p palette Generic Function 

Returns t if the palette supports color, otherwise returns nil. 

You can determine whether or not a particular stream or medium supports color 
with the following function: 

(defun color-stream-p (stream) 
(cl im : pal ette-col or-p 

(cl im: port-default-palette (dim: port stream)))) 
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climrpane Class 

The protocol class that corresponds to any kind of CLIM pane (that is, a sheet 
that participates in the layout protocol within an application frame). 



clim:pane-frame pane Generic Function 

Returns the application frame in which pane is one of the panes. 

clim:pane-name pane Generic Function 

Returns the name of the pane pane if it is a named pane, otherwise returns nil. 

climrpane-viewport pane Generic Function 

If the pane pane is part of a scroller pane, this returns the viewport pane for 
pane. Otherwise it returns nil. 

climrpane-viewport-region pane Generic Function 

If the pane pane is part of a scroller pane, this returns the region of pane's view- 
port. Otherwise it returns nil. 

The region is usually an instance of climrstandard-bounding-rectangle. 

climrpanep object Generic Function 

Returns t if and only if object is of type climrpane. 

conditionsrparse-error Condition 

This is the superclass of both climrsimple-parse-error and clim:input-not-of- 
required-type. 

clim:parse-text-style text-style Generic Function 

If text-style is either a text style object or a device font, clim:parse-text-style re- 
turns text-style. Otherwise, text-style must be a list of three elements, the text style 
family, face, and size. In this case, text-style is parsed and a text style object is re- 
turned. 

(cl im: parse-text-style '(:fix : roman : normal)) 
=> #<CLIM:STANDARD-TEXT-STYLE : FIX. : ROMAN .: NORMAL 20153772131> 

(cl im: parse-text-style '(:serif :bold-ital ic :normal)) 
=> #<CLIM:STANDARD-TEXT-STYLE : SERIF .(: BOLD : ITALIC) .: NORMAL 401035455> 

See the section "Text Styles in CLIM". 
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clim:partial-command-p command Function 

Returns t if the command object command is a partial command, otherwise returns 
nil. 



climr*partial-command-parser* Variable 

The currently active partial command parsing function. 

The default for this is climrcommand-line-read-remaining-arguments-for-partial- 
command when there is at least one interactor pane in the application frame, oth- 
erwise the default is climrmenu-read-remaining-arguments-for-partial-command. 

climrpath Class 

This is a subclass of climrregion that denotes regions that have dimensionality 1. 
If you want to create a new class that obeys the path protocol, it must be a sub- 
class of climrpath. 

Making a climrpath object with no length canonicalizes it to climr+nowhere+. 
When paths are used to construct an area by specifying its outline, they need to 
have a direction associated with them. 

climrpathp object Generic Function 

Returns t if and only if object is of type climrpath. 

clim-lisprpathname Clim Presentation Type 

The presentation type that represents a pathname. 

The options are rdefault-type (which defaults to nil), r default- version (which de- 
faults to mewest), and rmerge-default (which defaults to t). If rmerge-default is 
nil, climraccept returns the exact pathname that was entered, otherwise 
climraccept merges against the default provided to climraccept and rdefault-type 
and r default- version, using merge-pathnames. If no default is specified, it de- 
faults to *default-pathname-defaults*. 

climrpattern-height pattern Generic Function 

Returns the height of the pattern pattern. 

climrpattern-width pattern Generic Function 

Returns the width of the pattern pattern. 

climrpixmap-depth pixmap Generic Function 



Page 1605 



Returns the depth of the pixmap pixmap. 

climrpixmap-height pixmap Generic Function 

Returns the height of the pixmap pixmap. 

clim:pixmap-width pixmap Generic Function 

Returns the width of the pixmap pixmap. 

climrpoint Class 

The protocol class that corresponds to a mathematical point. If you want to create 
a new class that obeys the point protocol, it must be a subclass of climrpoint. 

climrpoint-position point Generic Function 

Returns two values, the X and Y coordinates of point. 

clim:point-x point Generic Function 

Returns the X coordinate of point. 

clim:point-y point Generic Function 

Returns the Y coordinate of point. 

climrpointer Class 

The protocol class that corresponds to a pointing device, such as a mouse. If you 
want to create a new class that obeys the pointer protocol, it must be a subclass of 
climrpointer. 

climrpointer-button-event Class 

The class that corresponds to some sort of CLIM pointer button event, such as a 
button press or release. This is a subclass of climrpointer-event. 

climrpointer-button-press-event Class 

The class that corresponds to the user pressing a button on the pointer. This is a 
subclass of climrpointer-button-event. 

climrpointer-button-release-event Class 
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The class that corresponds to the user releasing a button on the pointer. This is a 
subclass of clim:pointer-button-event. 

Note that CLIM will usually not pass button release events to the stream layer, 
except in specific circumstances, such as inside of climrtracking-pointer. That is, 
functions like read-char and climrread-gesture will not generally ever seen point- 
er button release events. 



clim:pointer-button-state pointer Generic Function 

Returns the current button state for pointer. This is a bit mask that can be 
checked against the values of clim:+pointer-left-button+, clim:+pointer-middle- 
button+, and clim:+pointer-right-button+. 



climrpointer-cursor pointer Generic Function 

Returns the current cursor type for pointer. 

You can use setf on climrpointer-cursor to temporarily change the cursor type. 
Note that some window managers can change the pointer cursor without notifying 
the application, so it is generally better to change the pointer cursor by setting 
the climrsheet-pointer-cursor attribute of the sheets for which you want the cur- 
sor to change. 

The valid cursor types are rdefault, rvertical-scroll, :scroll-up, :scroll-down, 
rhorizontal-scroll, :scroll-left, :scroll-right, :busy, :upper-left, :upper-right, 
:lower-left, :lower-right, : vertical-thumb, :horizontal-thumb, rbutton, rprompt, 
move, rposition, and :i-beam. 

For example, you can temporarily change the pointer cursor to indicate that the 
current program is busy using the following code: 

(defmacro with-busy-cursor ((&optional (frame 'cl im:*appl i cation-frame*)) 

&body body) 
(let ((pointer '#:pointer) 

(old-cursor '#:old-cursor)) 
'(let* ((, pointer (cl im:port-pointer (port , frame))) 
(, old-cursor (cl im:pointer-cursor , pointer))) 
(setf (cl im:pointer-cursor , pointer) :busy) 
(unwind-protect 
,@body 
(setf (cl im:pointer-cursor , pointer) , old-cursor))))) 



clim:pointer-documentation-pane Class 

The pane class that is used to implement the pointer documentation pane. It corre- 
sponds to the pane type abbreviation rpointer-documentation in the rpanes clause 
of clim:define-application-frame. 
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For clim:pointer-documentation-pane, the default for the : display- time option is 
nil, and the default for the :scroll-bars option is nil. 



clim:pointer-documentation-view Class 

The view that is used for pointer documentation. 

clim:*pointer-documentation-output* Variable 

Either nil or a stream to which pointer documentation should be written. If nil, no 
pointer documentation is computed. 

clim:+pointer-documentation-view+ Variable 

An instance of the class clim:pointer-documentation-view. 

clim:pointer-event Class 

The class that corresponds to some sort of CLIM pointer event. This is a subclass 
of clim:device-event. 

clim:pointer-event-button pointer-button-event Generic Function 

Returns the button number that was pressed when the pointer button event point- 
er-button-event occurred. The returned value is an integer with 1 bits that corre- 
spond to the button that was pressed. 

Button Mask 

Left clim:+pointer-left-button+ 

Middle clim:+pointer-middle-button+ 

Right clim:+pointer-right-button+ 



clim:pointer-event-x pointer-event Generic Function 

Returns the X position of the pointer when the pointer event pointer-event oc- 
curred. 



clim:pointer-event-y pointer-event Generic Function 

Returns the Y position of the pointer when the pointer event pointer-event oc- 
curred. 



clim:pointer-enter-event Class 
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The class that corresponds to the user moving the pointer into a sheet from anoth- 
er sheet. This is a subclass of clim:pointer-event. 



clim:pointer-exit-event Class 

The class that corresponds to the user moving the pointer out of a sheet. This is a 
subclass of clim:pointer-event. 



clim:pointer-input-rectangle* &key deft stop .-right .-bottom (.stream *standard- 
input*) .-pointer .-multiple-window (:finish-on-release t) Function 

You can use this function to prompt for and input the corners of a rectangle on 
the stream .stream (which defaults to *standard-input*). .-pointer, 
.-multiple-window, and :finish-on-release are as for climrdrag-output-record. 

If .-left and stop are provided, the upper left corner of the rectangle will be placed 
at (:left,:top). If .-right and .-bottom are provided, the lower right corner of the rect- 
angle will be place at (-.right, -.bottom). Otherwise, the upper left corner of the rect- 
angle is selected by pressing a button on the pointer. 

clim:pointer-input-rectangle* returns four values, the left, top, right, and bottom 
corners of the rectangle. 



clim:+pointer-left-button+ Constant 

The value returned by clim:pointer-event-button that corresponds to the user hav- 
ing pressed or released the lefthand button on the pointer. 



clim:+pointer-middle-button+ Constant 

The value returned by clim:pointer-event-button that corresponds to the user hav- 
ing pressed or released the middle button on the pointer. 



clim:pointer-motion-event Class 

The class that corresponds to the user moving the pointer. This is a subclass of 
clim:pointer-event. 



climrpointer-native-position pointer Generic Function 

This function returns the position (as two coordinate values) of the pointer pointer 
in the coordinate system of the port's graft (that is, its "root window"). 

You can use clim:pointer-set-position to set the pointer's native position. 



clim:pointer-place-rubber-band-line* &key :start-x :start-y (-.stream *standard- 
input*) -.pointer -.multiple-window (:finish-on-release t) Function 
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You can use this function to prompt for and input the end points of a line on the 
stream stream (which defaults to *standard-input*). .-pointer, -.multiple-window, and 
:finish-on-release are as for climrdrag-output-record. 

If :start-x and :start-y are provided, the start point of the line is at (:start-x,:start-y). 
Otherwise, the start point of the line is selected by pressing a button on the 
pointer. 

clim:pointer-place-rubber-band-line* returns four values, the start X and Y posi- 
tions, and the end X and Y positions. 



climrpointer-position pointer Generic Function 

This function returns the position (two coordinate values) of the pointer pointer in 
the coordinate system of the sheet that the pointer is currently over. 

You can use clim:pointer-set-position to set the pointer's position. 



clim:+pointer-right-button+ Constant 

The value returned by clim:pointer-event-button that corresponds to the user hav- 
ing pressed or released the righthand button on the pointer. 



clim:pointer-set-native-position pointer x y Generic Function 

This function changes the position of the pointer pointer to be (x,y). x and y are in 
the coordinate system of the port's graft (that is, its "root window"). 



clim:pointer-set-position pointer x y Generic Function 

This function changes the position of the pointer pointer to be (x,y). x and y are in 
the coordinate system of the sheet that the pointer is currently over. 



clim:pointer-sheet pointer Generic Function 

Returns the sheet over which the pointer pointer is currently positioned. 

climrpointerp object Generic Function 

Returns t if and only if object is of type climrpointer, otherwise returns nil. 

climrpointp object Generic Function 

Returns t if and only if object is of type climrpoint. 

climrpolygon Class 
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The protocol class that corresponds to a mathematical polygon. This is a subclass 
of climrarea. If you want to create a new class that obeys the polygon protocol, it 
must be a subclass of climrpolygon. 



climrpolygon-points polygon Generic Function 

Returns a sequence of points that specify the segments in polygon. 

climrpolygonp object Generic Function 

Returns t if and only if object is of type climrpolygon. 

climrpolyline Class 

The protocol class that corresponds to a polyline. This is a subclass of climrpath. 
If you want to create a new class that obeys the polyline protocol, it must be a 
subclass of climrpolyline. 

climrpolyline-closed polyline Generic Function 

Returns t if polyline is closed, otherwise returns nil. 

climrpolylinep object Generic Function 

Returns t if and only if object is of type climrpolyline. 

climrport Class 

The protocol class that corresponds to a port. If you want to create a new class 
that obeys the port protocol, it must be a subclass of climrport. 

climrport object Generic Function 

Given a CLIM object object, climrport returns the port associated with object. If ob- 
ject is not presently "owned" by any port, climrport will return nil. 

You can call climrport on sheets, mediums, frames, frame managers, pointers, cur- 
sors, and pixmaps. 

climrport-default-palette port Generic Function 

Returns the palette associated with the port port. 

A palette is an object that contains mappings from color names (which are strings 
or symbols) to CLIM color objects. See the section "Predefined Color Names in 
CLIM". 
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clim:port-modifier-state basic-port Generic Function 

Returns the state of the modifier keys for the port port. This is a bit mask that 
can be checked against the values of clim:+shift-key+, clim:+control-key+, 
clim:+meta-key+, clim:+super-key+, and clim:+hyper-key+. 



clim:port-name port Generic Function 

Returns the name of the port as a string whose syntax varies from port to port. 
For example, a Genera port might have a name of "Summer: Main Screen". 



climrport-pointer port Generic Function 

Returns the pointer object corresponding to the primary pointing device for the 
port port. 

The pointer is of type climrpointer. 



clim:port-server-path port Generic Function 

Returns the server path associated with the port. For example, a Genera port 
might return the following: 

(:genera :screen #<MAIN-SCREEN Main Screen 20006600000 exposecb) 



clim:port-type port Generic Function 

Returns the type of the port, that is, the first element of the server path specifica- 
tion (rgenera, :clx, and so on). 



climrportp object Generic Function 

Returns t if and only if object is of type climrport, otherwise returns nil. 

clim:position-sheet-carefully sheet x y Function 

Moves the sheet sheet to the position specified by x and y, taking care not to move 
the sheet outside of its parent (for example, off the screen). 

This function is intended to work only on top level sheets. If you call it on a sheet 
that is not a top level sheet, the results are unpredictable. For example, if you 
want to position an application frame, do the following: 

(cl im: position-sheet-careful ly 

(cl im: frame-top-level -sheet frame) x y)) 

clim:position-sheet-near-pointer sheet &optional x y Function 
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Moves the sheet sheet to a position near the current pointer position. If x and y 
are supplied, these override the pointer position. clim:position-sheet-near-pointer 
takes care not to move the sheet outside of its parent (for example, off the 
screen). 

This function is intended to work only on top level sheets. If you call it on a sheet 
that is not a top level sheet, the results are unpredictable. 



clim:*possibilities-gestures* Variable 

A list of gesture names that cause clim:complete-input to display a help message 
and the list of possibilities. On most systems, this includes the gesture correspond- 
ing to the ttsControl-? character. 



climrpresent object &optional (presentation-type (clim:presentation-type-of object),) 
&key (.stream *standard-output*) (:view (clim:stream-default-view stream}) .-mod- 
ifier .-acceptably (:for-context-type presentation-type) .single-box :allow-sensitive- 
inferiors sensitive (-record-type 'climrstandard-presentation) Function 

Creates a presentation on the stream of the specified object, using the given type 
and view to determine visual appearance. The manner in which the object is dis- 
played depends on the presentation type of the object; the display is done by the 
type's climrpresent method for the given view. 

For background information, see the section "Presentation Types in CLIM". 

object The object to be presented. 

presentation-type 

A presentation type specifier, which may be a presentation type ab- 
breviation. This defaults to the most specific type that CLIM can 
determine, based on the Lisp data type of object. 

stream 

The stream to which output should be sent. The default is 
*standard-output*. 

An object representing a view. The default is (climrstream-default- 
view stream). For most streams, the default view is the textual 
view, clim:+textual-view+. For dialog streams (that is, within 
climraccepting-values), the view will typically be either 
clim:+textual-dialog-view+ or clim:+gadget-dialog-view+. 

Specifies a function of one argument (the new value) that can be 
called in order to store a new value for object after the user edits 
the presentation. The default is nil. 

.-acceptably 

Defaults to nil, which requests the climrpresent method to produce 



-.view 



-.modifier 
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output designed to be read by the user. If t, this option requests 
the climrpresent method to produce output that can be parsed by 
the climraccept method. This option makes no difference for most 
presentation types. 

:for-context-type 

A presentation type indicating an input context. The present method 
can look at this to determine if the object should be presented dif- 
ferently. For example, the climrpresent method for the 
climrcommand presentation type uses this in order to determine 
whether or not to display a colon (":") before commands in 
clim:command-or-form contexts. :for-context-type defaults to presen- 
tation-type. 

:single-box 

Controls how CLIM determines whether the pointer is pointing at 
this presentation and controls how this presentation is highlighted 
when it is sensitive. 

The possible values are: 

t If the pointer's position is inside the bounding 

rectangle of this presentation, it is considered to 
be pointing at this presentation. This presentation 
is highlighted by highlighting its bounding rectan- 
gle. 

nil If the pointer is pointing at a visible piece of out- 

put (text or graphics) drawn as part of the visual 
representation of this presentation, it is considered 
to be pointing at this presentation. This presenta- 
tion is highlighted by highlighting every visible 
piece of output that is drawn as part of its visual 
representation. This is the default. 

rposition Like t for determining whether the pointer is 

pointing at this presentation, like nil for high- 
lighting. 

rhighlighting Like nil for determining whether the pointer is 
pointing at this presentation, like t for highlight- 
ing. 

Supplying :single-box rhighlighting is useful when the default be- 
havior produces an ugly appearance (for example, a very jagged 
highlighting box). 

Supplying :single-box rposition is useful when the visual represen- 
tation of a presentation consists of one or more small graphical ob- 
jects with a lot of space between them. In this case the default be- 
havior offers only small targets that the user might find difficult to 
position the pointer over. 
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:allow-sensitive-inferiors 

When :allow-sensitive-inferiors is nil, it indicates that nested calls to 
climrpresent or clim:with-output-as-presentation inside this one 
should not generate presentations. The default is t. 

sensitive 

If sensitive is nil, no presentation is produced. The default is t. 

■.record-type 

This option is useful when you have defined a customized record 
type to replace CLIM's default record type. It specifies the class of 
the output record to be created. 



climrpresent type-key parameters options object type stream view &key acceptably 
:for-context-type Clim Presentation Method 

This presentation method is responsible for displaying the representation of object 
having type type for a particular view view. The method's caller takes care of cre- 
ating the presentation, so the method need only display the content of the presen- 
tation. 

The method must specify &key, but need only receive the keyword arguments that 
it is interested in. The remaining keyword arguments will be ignored automatically 
since the generic function specifies &allow-other-keys. 

The climrpresent method can specialize on the view argument in order to define 
more than one view of the data. For example, a spreadsheet program might define 
a presentation type for revenue, which can be displayed either as a number or a 
bar of a certain length in a bar graph. Typically, at least one canonical view 
should be defined for a presentation type; for example, you should define a 
climrpresent method specializing on the class climrtextual-view if you want to al- 
low the type to be displayed textually. 

Note that CLIM stores the presentation type for its own use, so you should not 
modify it once you have handed it to CLIM. 

For more information on defining presentation types, see the section "Defining a 
New Presentation Type in CLIM". 



climrpresent-to-string object &optional (presentation-type (climrpresentation-type- 
of object),) &key (:view climr+textual-view+J .-acceptably (:for-context-type 
presentation-type) .string .-index Function 

Presents an object into a string in such a way that it can subsequently be accept- 
ed as input by climraccept-from-string. climrpresent-to-string is the same as 
climrpresent within with-output-to-string. 

object, presentation-type, -.view, -.acceptably, and :for-context-type are as for 
climrpresent. 

For background information, see the section "Presentation Types in CLIM". 
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climrpresentation Class 

The protocol class that corresponds to a presentation. If you want to create a new 
class that obeys the presentation protocol, it must be a subclass of 
climrpresentation. 

climrpresentationp object Function 

Returns t if and only if object is of type climrpresentation. 

climrpresentation-matches-context-type presentation context-type frame window x y 
&key -.event (.-modifier-state 0) Function 

Returns a non-nil value if there are any translators that translate from presenta- 
tion's type to context-type. (There is no from-type argument because it is derived 
from presentation.) frame, window, x, y, .-event, and .-modifier-state are as for 
climrfind-applicable-translators. 

If there are no applicable translators, climrpresentation-matches-context-type will 
return nil. 



climrpresentation-object presentation Generic Function 

Returns the application object represented by the presentation presentation. You 
can use setf on climrpresentation-object to change the object associated with the 
presentation. 

Any class that is a subclass of climrpresentation must implement this method. 



climrpresentation-refined-position-test type-key parameters options type record x y 

Clim Presentation Method 

CLIM uses this method to definitively answer hit detection queries for a presenta- 
tion, that is, determining whether or not the point (x,y) is contained within the 
output record record. Its contract is exactly the same as for climroutput-record- 
refined-position-test, except that it is intended to specialize on the presentation 
type type. 

It can be useful to define a climrpresentation-refined-position-test method when 
the displayed output records that represent the presentation do not themselves im- 
plement the desired hit detection behavior. In practice, this comes up only rarely, 
since using the rsingle-box option to climrpresent and climrwith-output-as- 
presentation will often produce the desired behavior. 



climrpresentation-replace-input stream object type view &key irescan -.buffer-start 

Generic Function 

This is like climrreplace-input, except that the new input to insert into the input 
buffer is gotten by presenting the object object with the presentation type type and 
view view . 
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srescan and :buffer-start are the same as for clim:replace-input. 

For example, the following climraccept method reads a token followed by a "sys- 
tem" or a pathname, but if the user clicks on either a "system" or a pathname, it 
inserts that object into the input buffer and returns: 

(cl im:def ine-presen tat ion-method cl im: accept 

((type library) stream (view cl im: textual-view) 
&key default) 
(cl im:with-input-context ('(or system pathname)) (object type) 

(let ((system (dim: accept ' (cl im: token-or-type (: private) system) 

: stream stream :view view 
:prompt nil : display-default nil 
:default default 

additional -del i miter-gestures ' (#\space))) 
file) 
(let ((char (cl im: read-gesture : stream stream))) 
(unless (eql char #\space) 

(cl im: unread-gesture char : stream stream)) 
(when (eql system ':private) 

(setq file (clim:accept 'pathname 

: stream stream :view view 
: prompt "library pathname" 
: display-default t))) 
(if (eql system ':private) file system))) 
(t (cl im:presentation-replace-input stream object type view) 
(values object type)))) 

See the section "Utilities for climraccept Presentation Methods". See the section 
"The Structure of the CLIM Input Editor". 



climrpresentation-subtypep type putative-supertype Function 

Answers the question "Is the type specified by type a subtype of the type specified 
by putative-supertypeT' . Neither type nor putative-subtype may be presentation type 
abbreviations. 

This function is analogous to subtypep. 

climrpresentation-subtypep returns two values, subtypep and known-p. subtypep 
can be t (meaning that type is definitely a subtype of putative-supertype) or nil 
(meaning that type is definitely not a subtype of putative-supertype when known-p 
is t, or that the answer cannot be determined if known-p is nil). 

See the clim presentation method climrpresentation-subtypep for a detailed de- 
scription of how this works. 



climrpresentation-subtypep type-key type putative-supertype 

Clim Presentation Method 
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This presentation method is called when the climrpresentation-subtypep function 
requires type-specific knowledge. 

The climrpresentation-subtypep function walks the type lattice to determine that 
type is a subtype of putative-supertype, without looking at the type parameters. 
When a supertype of type has been found whose name is the same as the name of 
putative-supertype, then the climrpresentation-subtypep method for that type is 
called in order to resolve the question by looking at the type parameters (that is, 
if the climrpresentation-subtypep method is called, type and putative-supertype are 
guaranteed to be the same type, differing only in their parameters). 

Unlike all other presentation methods, climrpresentation-subtypep receives a type 
argument that has been translated to the presentation type for which the method 
is specialized; type is never a subtype. The method is only called if putative- 
supertype has parameters and the two presentation type specifiers do not have 
equal parameters. 

climrpresentation-subtypep returns two values, subtypep and known-p. subtypep 
can be t (meaning that type is definitely a subtype of putative-supertype) or nil 
(meaning that type is definitely not a subtype of putative-supertype when known-p 
is t, or that the answer cannot be determined if known-p is nil). 

Since climrpresentation-subtypep takes two arguments that are presentation 
types, the parameters are not lexically available as variables in the body of a pre- 
sentation method. Use climrwith-presentation-type-parameters if you want to ac- 
cess the parameters of the presentation types. 

Noter You must define a climrpresentation-subtypep method if the presentation 
type has parameters. 

For example, the CLIM presentation type complex has a type parameter that indi- 
cates what numeric type the real and imaginary components of the number must 
be. Its climrpresentation-subtypep method could be written as follows: 

(cl im:def ine-presen tat ion-method cl im:presentation-subtypep 

((type complex) putative-supertype) 
(let ((typel 

(cl im:with-presentat ion- type-parameters 
(complex type) type)) 
(type2 

(cl im:with-presentat ion- type-parameters 
(complex putative-supertype) type))) 
(cond ((eq type2 '*) 
(values t t)) 
((eq typel '*) 

(values nil t)) 
(t 
(cl im:presentation-subtypep typel type2))))) 



climrpresentation-type presentation Generic Function 
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Returns the presentation type of the presentation presentation. You can use setf on 
clim:presentation-type to change the presentation type associated with the pre- 
sentation. 

Any class that is a subclass of climrpresentation must implement this method. 



clim:presentation-type-of object Function 

Returns the presentation type of the object object. If the type cannot be readily 
computed, this may return t or climrexpression. 

This function is analogous to type-of. 



clim:presentation-type-specifier-p type-key parameters options type 

Clim Presentation Method 

This presentation method is responsible for checking the validity of the parameters 
and options. The default method returns t. 



clim:presentation-typep object type Function 

Returns t if object is of the type specified by type, otherwise returns nil. type may 
not be a presentation type abbreviation. 

This function is analogous to typep. 



clim:presentation-typep type-key parameters object type Clim Presentation Method 

This presentation method is called when the clim:presentation-typep function re- 
quires type-specific knowledge. If the type name in type is or names a CLOS class, 
the method is called only if object is a member of the class and type contains pa- 
rameters, and the method simply tests whether object is a member of the subtype 
specified by the parameters. For non-class types, the method is always called. 

Note: You must define a clim:presentation-typep method if the presentation type 
does not have the same name as a CLOS class. 

For example, the CLIM presentation type complex has a type parameter that indi- 
cates what numeric type the real and imaginary components of the number must 
be. Its clim:presentation-typep method could be written as follows: 

(cl im:def ine-presen tat ion-method cl im:presen tat ion- typep 

(object (type complex)) 
(declare (ignore type)) 
(or (eq type '*) 

(and (cl im:presentation-typep (realpart object) type) 

(cl im:presentation-typep (imagpart object) type)))) 



clim:print-menu-item menu-item &optional (stream *standard-output*J Function 
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Given a menu item menu-item, display it on the stream stream. This is the func- 
tion that climrmenu-choose uses to display menu items if no printer is supplied. 



clim-sys:process-name process Function 

Returns the name of the process process. 

clim-sys:processp object Function 

Returns t if object is a process, otherwise returns nil. 
See the section "Multi-processing in CLIM". 

clim-sys:process-interrupt process function Function 

Interrupts the process process and causes it to evaluate the function function. 

On systems that do not support multi-processing, this is equivalent to simply call- 
ing function. 

clim-sys:process-wait wait-reason predicate Function 

Causes the current process to wait until predicate returns a non-nil value, predi- 
cate is a function of no arguments, reason is a "reason" for waiting, usually a 
string. 

On systems that do not support multi-processing, clim-sys:process-wait will simply 
loop until predicate returns a non-nil value. 

See the section "Multi-processing in CLIM". 

clim-sys:process-wait-with-timeout wait-reason timeout predicate Function 

Causes the current process to wait until either predicate returns a non-nil value or 
the number of seconds specified by timeout has elapsed, predicate is a function of 
no arguments, reason is a "reason" for waiting, usually a string. 

On systems that do not support multi-processing, clim-sys:process-wait-with- 
timeout will simply loop until predicate returns a non-nil value, or the timeout has 
elapsed. 

See the section "Multi-processing in CLIM". 

clim-sys:process-yield Function 

Allows other processes to run. On systems that do not support multi-processing, 
this does nothing. 

See the section "Multi-processing in CLIM". 
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climrpush-button Class 

The climrpush-button gadget class provides press-to-activate switch behavior. It is 
a subclass of climraction-gadget and climrlabelled-gadget-mixin. 

See the section "Using Gadgets in CLIM". 

In addition to the initargs for climraction-gadget and the usual pane initargs 
(rforeground, rbackground, rtext-style, space requirement options, and so forth), 
the following initargs are supported: 

rlabel A string or pixmap that is used to label the button. 

rshow-as-default-p 

When t, the push button will be drawn with a heavy border, which 
indicates that this button is the "default operation". The default is 
nil. 

rpattern If supplied, this is a pattern (created by climrmake-pattern) that 
specifies that shape of the button. The default pattern for CLIM's 
"native" gadgets is a rectangular button that is just big enough to 
enclose the label. 

rexternal-label 

If supplied, this is a string that will be used as a label that is 
drawn outside of the push button instead of inside of the button. 

climrarmed-callback will be invoked when the push button becomes armed (such 
as when the pointer moves into it, or a pointer button is pressed over it). When 
the button is actually activated (by releasing the pointer button over it), 
climractivate-callback will be invoked. Finally, climrdisarmed-callback will be in- 
voked after climractivate-callback, or when the pointer is moved outside of the 
button. 

A push button might be created as follows: 

(cl im: make-pane 'cl im: push-button 
: label "Button" 
:activate-cal lback 'push-button-cal lback) 

(defun push-button-callback (button) 

(format t "~&Button ~A pushed" (cl im: gadget-label button))) 



climrqueue-event sheet event Generic Function 

CLIM's event processor calls this function to insert the event event into the queue 
of events for sheet. 

CLIM always handles some events immediately, such as window repaint events. In 
this case, instead of inserting the event into the event queue, the climrqueue- 
event method will call climrhandle-event directly. 
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Some sheets in CLIM also handle certain other events immediately. For example, 
scroll bars in CLIM respond to pointer events even when user applications are not 
waiting for input. Such sheets specialize the clim:queue-event method to call 
clim:handle-event directly. 



climrqueue-repaint sheet repaint-event Generic Function 

Inserts the repaint event repaint-event into sheet's, event queue. A program that 
reads events out of the queue will be expected to call climrhandle-repaint for the 
sheet using the repaint region gotten from the event. 



climrqueue-rescan input-editing-stream &optional rescan-type Generic Function 

Indicates that a rescan operation on input-editing-stream should take place after 
the next non-input editing gesture is read. This works by setting the "rescan 
queued" flag to t. Use this function when you are writing new "destructive" input 
editing commands. 

For more information on the input editor, see the section "The Structure of the 
CLIM Input Editor". 



clim:radio-box Class 

A radio box is a special kind of gadget that contains one or more toggle buttons. 
At any one time, only one of the buttons managed by the radio box may be "on". 
The contents of a radio box are its buttons, and as such a radio box is responsible 
for laying out the buttons that it contains. 

It is a subclass of climrvalue-gadget and clim:oriented-gadget-mixin. 

See the section "Using Gadgets in CLIM". 

In addition to the initargs for climrvalue-gadget and the usual pane initargs 
(rforeground, rbackground, rtext-style, space requirement options, and so forth), 
the following initargs are supported: 

rselectionThis is used to specify which button, if any, should be initially se- 
lected. 

rchoices This is used to specify all of the buttons that serve as choices. 

As the current selection changes, the previously selected button and the newly se- 
lected button both have their climrvalue-changed-callback handlers invoked. 

Calling climrgadget-value on a radio box will return the currently selected toggle 
button. The value of the radio box can be changed by calling setf on climrgadget- 
value. 

A radio box might be created as follows, although it is generally more convenient 
to use climrwith-radio-box: 
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(let* ((choices 

(list (cl im: make-pane 'cl im: toggle-button 
: label "One" :width 80) 
(cl im: make-pane 'cl im: toggle-button 

: label "Two" :width 80) 
(cl im: make-pane 'cl im: toggle-button 
: label "Three" :width 80))) 
(current (second choices))) 
(cl im:make-pane 'cl im: radio-box 
:choices choices 
selection current 
: val ue-changed-cal 1 back ' radi o-val ue-changed-cal 1 back) ) 

(defun radi o-val ue-changed-cal 1 back (radio-box value) 
(declare (ignore radio-box)) 
(format t "~&Radio box toggled to ~S" value)) 



clim:radio-box-current-selection radio-box Generic Function 

Returns the current selection for the radio box. The current selection will be one 
of the toggle buttons in the radio box. 

You can use setf on this in order to set the current selection for the radio box, or 
you can use setf on clim:gadget-value of the radio box to accomplish the same 
thing. 



clim:radio-box-selections radio-box Generic Function 

Returns a sequence of all of the selections in the radio box. The elements of the 
sequence will be toggle buttons. 



clim:radio-box-view Class 

The class that represents the view corresponding to a radio box. This is usually 
used for a "one of" choice, as in a member presentation type. 



clim:+radio-box-view+ Constant 

An instance of the class clim:radio-box-view. 

clim:raise-frame frame Generic Function 

Raises the application frame frame so that it is on top of all of the other host win- 
dows by calling clim:raise-sheet on the frame's top-level sheet. This does not 
change the state of the frame, it simply makes it visible on the screen. 
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clim:range-gadget-mixin Class 

The class that is mixed in to a gadget that has a range, for example, a slider. 

All subclasses of clim:range-gadget-mixin must handle the two initargs :min- 
value and :max-value, which are used to specify the minimum and maximum val- 
ue of the gadget. 

ratio &optional low high Clim Presentation Type 

The presentation type that represents a ratio between low and high. Options to 
this type are :base and rradix, which are the same as for the integer type. It is a 
subtype of rational. 

rational &optional low high Clim Presentation Type 

The presentation type that represents either a ratio or an integer between low and 
high. Options to this type are :base and rradix, which are the same as for the 
integer type. It is a subtype of real. 



climrread-command command-table &key (.stream *query-io*J (.-command-parser 
climr*command-parser*J (xommand-unparser climr*command-unparser*J (ipartial- 
command-parser climr*partial-command-parser*J mse-keystrokes Function 

Reads a command from the user via command lines or the pointer. This function 
is not normally called by programmers. 

command-table 

Specifies the command table from which commands should be read. 

.stream The stream from which to read the command. 

.■use-keystrokes 

The default for this is nil. If it is t, climrread-command calls 
climrread-command-using-keystrokes to read the command. The 
keystroke accelerators are those generated by climrwith-command- 
table-keystrokes. 

.■command-parser 

A function of two arguments, command-table and stream. This func- 
tion should read a command from the user and return a command 
object. 

xommand-unparser 

A function of three arguments, command-table, stream, and com- 
mand-to-unparse. The function should print a textual description of 
the command and the set of arguments supplied on stream. 

:partial-command-parser 

A function of four arguments, command-table, stream, partial- 
command, and start-position. A partial command is a command 
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structure with climr*unsupplied-argument-marker* in place of any 
argument that remains to be filled in. The function should read the 
remaining arguments in any way it sees fit and should return a 
command object, start-position is the original input-editor scan posi- 
tion of stream if stream is an interactive stream. 

You should not normally supply the : command-parser, xommand-unparser, or :par- 
tial-command-parser arguments. CLIM will arrange to choose the correct default 
values for these. 



clim:read-command-using-keystrokes command-table keystrokes &key (.stream 
*query-io*J (: command-parser climr*command-parser*) (xommand-unparser 
climr*command-unparser*) (:partial-command-parser climr*partial-command- 
parser*) Function 

Reads a command from the user via a command line, the pointer, or typing a sin- 
gle keystroke. It returns either a command object, or a key press event if the user 
typed a keystroke that is in keystrokes but does not have a command associated 
with it in the command table. 

keystrokes is a list of gesture specs. The other arguments are as for climrread- 
command. 

See also clim:with-command-table-keystrokes. 



clim:read-frame-command frame &key .stream Generic Function 

clim:read-frame-command reads a command from the user on the stream .stream, 
and returns the command object, frame is an application frame. 

The default method for clim:read-frame-command calls climrread-command on 
frame's current command table. You can specialize this generic function for your 
own application frames, for example, if you want to have your application be able 
to read commands using keystroke accelerators. 



climrread-gesture &key (stream *standard-input*J .-timeout :peek-p :input-wait-test 
:input-wait-handler :pointer-button-press-handler Function 

Returns the next gesture available in the input stream (either a character or a 
pointer button event). Note that climrread-gesture does not echo its input; CLIM's 
input editor does this when reading input inside of a call to climrwith-input- 
editing. 

When a user types any sort of abort gesture (such as ttsRbort on Genera), the 
climrabort-gesture condition is signalled. 

.■timeout Specifies the number of seconds that climrread-gesture will wait 
for input to become available. If no input is available, climrread- 
gesture will return the two values, nil and rtimeout. The default is 
that there is no timeout. 
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:peek-p If t, specifies that the gesture returned will be left in the stream's 
input buffer. The default is nil. 

:input-wait-test 

The value of this argument is a function. The function will be in- 
voked with one argument, the stream. This argument will be passed 
on to clim:stream-input-wait. 

:input-wait-handler 

The value of this argument is a function. The function will be in- 
voked with one argument, the stream, when the invocation of 
clim:stream-input-wait returns, but no input gesture is available. 
This option can be used in conjunction with :input-wait-test to han- 
dle conditions other than user keystroke gestures. 

:pointer-button-press-handler 

The value of this is a function of one argument, a pointer button 
event. This function is invoked when the user clicks the pointer. 

You will rarely, if ever, need to supply :input-wait-test, :input-wait-handler, or 
:pointer-button-press-handler. CLIM uses these arguments to connect presentation 
types to streams. 



clim:read-token stream &key .-timeout :input-wait-handler :pointer-button-press- 
handler xlick-only Function 

Reads characters from stream until it encounters an activation gesture, a delimiter 
gesture, or a pointer gesture. All printing standard characters are acceptable 
(CLtL p. 336, CLtLII p. 512). clim:read-token returns the accumulated string that 
was delimited by an activation or delimiter gesture, leaving the delimiter unread, 
that is, still in the stream's input buffer. 

.-timeout Specifies the number of seconds that clim:read-token will wait 

for input to become available. If no input is available, 
clim:read-token will return the two values, nil and rtimeout. 

The default is that there is no timeout. 

xlick-only If true, only pointer gestures are expected and anything else 

will result in a beep. The default is nil. 

:input-wait-handler Passed along to climrread-gesture . The default is a function 
that supports highlighting for clim:with-input-context. 

:pointer-button-press-handler 

Passed along to climrread-gesture. The default is a function 
that supports presentation translators for climrwith-input- 
context. 

You will rarely, if ever, need to supply :input-wait-handler or :pointer-button-press- 
handler. CLIM uses these arguments to connect presentation types to streams. 
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future-common-lisprreal &optional low high Clim Presentation Type 

The presentation type that represents either a ratio, an integer, or a floating point 
number between low and high, low and high can be inclusive or exclusive, as in 
Common Lisp type specifiers. 

Options to this type are :base and rradix, which are the same as for the integer 
type. This type is a subtype of number. 



climrrectangle Class 

The protocol class that corresponds to an axis-aligned mathematical rectangle, that 
is, rectangular polygons whose sides are parallel to the coordinate axes. This is a 
subclass of climrpolygon. If you want to create a new class that obeys the rectan- 
gle protocol, it must be a subclass of climrrectangle. 



climrrectangle-edges* rectangle Generic Function 

Returns the coordinate of the minimum X and Y and maximum X and Y of rectan- 
gle as four values. 



climrrectangle-height rectangle Function 

Returns the height of rectangle. The height is the difference between the maxi- 
mum Y and the minimum Y. 



clim:rectangle-max-point rectangle Generic Function 

Returns the maximum point of rectangle. (The position of a rectangle is specified 
by its minimum point). 



clim:rectangle-max-x rectangle Function 

Returns the coordinate of the maximum X of rectangle. 

clim:rectangle-max-y rectangle Function 

Returns the coordinate of the maximum Y of rectangle. 

clim:rectangle-min-point rectangle Generic Function 

Returns the minimum point of rectangle. The position of a rectangle is specified by 
its minimum point. 

clim:rectangle-min-x rectangle Function 

Returns the coordinate of the minimum X of rectangle. 
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clim:rectangle-min-y rectangle Function 

Returns the coordinate of the minimum Y of rectangle. 

clim:rectangle-size rectangle Function 

Returns two values, the width and the height of rectangle. 

clim:rectangle-width rectangle Function 

Returns the width of rectangle. The width of a rectangle is the difference between 
the maximum X and the minimum X. 

climrrectanglep object Generic Function 

Returns t if and only if object is of type climrrectangle. 

clim:rectilinear-transformation-p transform Generic Function 

Returns t if transform will always transform any axis-aligned rectangle into anoth- 
er axis-aligned rectangle, otherwise returns nil. This category includes scalings as 
a subset, and also includes 90 degree rotations. 

Rectilinear transformations are the most general category of transformations for 
which the bounding rectangle of a transformed object can be found by transform- 
ing the bounding rectangle of the original object. 



clim:recompute-extent-for-changed-child record child old-left old-top old-right old- 
bottom Generic Function 

CLIM calls this function whenever the bounding rectangle of one of the children of 
a record has been changed. It updates the bounding rectangle of record to be large 
enough to completely contain the new bounding rectangle of the child output 
record child. CLIM notifies all of the ancestors of record by recursively calling 
clim:recompute-extent-for-changed-child. 

CLIM provides an rafter method on climrdelete-output-record that calls 
clim:recompute-extent-for-changed-child to inform the parent of the record that a 
change has taken place, so you will rarely need to call this yourself. 

See the section "Concepts of CLIM Output Recording". 



clim:recompute-extent-for-new-child record child Generic Function 

CLIM calls this function whenever a new child is added to an output record. It up- 
dates the bounding rectangle of record to be large enough to completely contain 
the new child output record child. CLIM notifies the parent of record, and all its 
ancestors, of the change in size by calling clim:recompute-extent-for-changed- 
child on all of record's ancestors. 
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CLIM provides and rafter method on climradd-output-record that calls 
clim:recompute-extent-for-new-child, so you will rarely need to call it yourself. 

See the section "Concepts of CLIM Output Recording". 



climrredisplay record stream &key (xheck-overlapping t) Function 

Causes the output of record to be recomputed by calling climrredisplay-output- 
record on record. CLIM redisplays the changes incrementally, that is, only redis- 
plays those parts of the record that changed, record must be an output record cre- 
ated by a previous call to climrupdating-output, and may be any part of the out- 
put history of stream. 

The .xheck-overlapping argument insures that climrredisplay will correctly redis- 
play output records that overlap at the same level in the output record hierarchy. 
It defaults to t. If you have output that you know does not not have any such over- 
lapping output records, you can pass in nil; this will speed up incremental redis- 
play, but at the risk of failing to draw some records due to overlap. 

See the section "Example of Incremental Redisplay in CLIM". 



clim:redisplay-frame-pane frame pane-name &key :force-p Generic Function 

Causes the pane pane-name of frame to be redisplayed immediately. CLIM either 
calls the pane's display function, or uses climrredisplay if the pane is using incre- 
mental redisplay. 

If :force-p is t, then the pane is forcibly redisplayed even if it is an incrementally 
redisplayed pane that would not otherwise require redisplay. 



climrredisplay-frame-panes frame &key force-p Generic Function 

Causes all of the panes of frame to be redisplayed immediately. If :force-p is t, 
then the panes are forcibly redisplayed even if they are incrementally redisplayed 
panes that would not otherwise require redisplay. 



climrredisplay-output-record record stream &optional check-overlapping x y 
parent-x parent-y Generic Function 

Causes the output of record to be recomputed. CLIM redisplays the changes incre- 
mentally, that is, only redisplays those parts of the record that changed, record 
must be an output record created by a previous call to climrupdating-output, and 
may be any part of the output history of stream. 

The optional arguments can be used to specify where on the stream the output 
record should be redisplayed, x and y represent where the cursor should be, rela- 
tive to the parent output record of record, before the record is redisplayed. The de- 
fault values for x and y are the starting position of the output record. 
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parent-x and parent-y can be supplied to say: do the output as if the superior start- 
ed at positions parent-x and parent-y (which are in absolute coordinates). The de- 
fault values for parent-x and parent-y are the absolute coordinate of the output 
record's parent. 

The check-overlapping argument insures that climrredisplay checks for overlapping 
records. It defaults to t. If you make it nil it speeds up redisplay, at the risk of 
failing to draw some records due to overlap. If you are sure that no sibling records 
overlap, you can use this argument to optimize redisplay. 

You can specialize this generic function for your own classes of output records, but 
you should not generally call this function yourself. 



clim:redraw-input-buffer input-editing-stream &optional start-position 

Generic Function 

Displays the input editor's buffer starting at the position start-position on the in- 
teractive stream that is encapsulated by the input editing stream input-editing- 
stream. 

You will rarely need to call this function yourself, since the input editor will al- 
most always do this for you. For more information on the input editor, see the sec- 
tion "The Structure of the CLIM Input Editor". 



clim:reflection-transformation-p transform Generic Function 

Returns t if transform inverts the "handedness" of the coordinate system, other- 
wise returns nil. Note that this is a very inclusive category. Transformations are 
considered reflections even if they distort, scale, or skew the coordinate system, as 
long as they invert the handedness. 



climrregion Class 

The protocol class that corresponds to a closed set of points. If you want to create 
a new class that obeys the region protocol, it must be a subclass of climrregion. 



climrregionp object Generic Function 
Returns t if and only if object is of type climrregion. 

climrregion-contains-position-p region x y Generic Function 

Returns t if the point (x,y) is contained in region, otherwise returns nil. Since re- 
gions in CLIM are closed, this will return t if (x,y) is on the region's boundary. 
This is a special case of climrregion-contains-region-p. 

climrregion-contains-region-p regionl region2 Generic Function 



Page 1630 



Returns t if all points in region2 are members of regionl, otherwise returns nil. 



climrregion-difference regionl region2 Generic Function 

Returns a region that contains all points in regionl that are not in region2 (plus 
additional boundary points to make the result closed). The result of climrregion- 
difference has the same dimensionality as regionl, or is clim:+nowhere+. For ex- 
ample, the difference of an area and a path produces the same area; the difference 
of a path and an area produces the path clipped to stay outside of the area. 



climrregion-equal regionl region2 Generic Function 

Returns t if regionl and region2 contain exactly the same set of points, otherwise 
returns nil. 



climrregion-intersection regionl region2 Generic Function 

Returns a region that contains all points that are in both regionl and region2 (pos- 
sibly with some points removed to satisfy the dimensionality rule). The result of 
climrregion-intersection has dimensionality that is the minimum dimensionality of 
regionl and region2, or is clim:+nowhere+. For example, the intersection of two 
areas is either another area or clim:+nowhere+; the intersection of two paths is 
either another path or clim:+nowhere+; the intersection of a path and an area 
produces the path clipped to stay inside of the area. 



clim:region-intersects-region-p regionl region2 Generic Function 

Returns nil if climrregion-intersection of the two regions would be 
clim:+nowhere+, otherwise returns t. 



clim:region-set Class 

The class that represents region sets; a subclass of region. 

clim:region-set-function region Generic Function 

Returns a symbol representing the operation that relates the regions in region. 
This will be one of the Common Lisp symbols union, intersection, or set- 
difference. For the case of region sets that are composed entirely of rectangular 
regions, CLIM canonicalizes the set so that the symbol will always be union. If re- 
gion is a region that is not a region-set, the result is always union. 

clim:region-set-regions region &key .-normalize Generic Function 

Returns a sequence of the regions in region, region can be either a clim:region-set 
or any member of climrregion, in which case the result is simply a sequence of 
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one element: region. For the case of region sets that are unions of rectangular re- 
gions, CLIM canonicalizes the set so that the rectangles returned by climrregion- 
set-regions are guaranteed not to overlap. 

If .-normalize is supplied, it may be either :x-banding or :y-banding. If it is :x- 

banding and all the regions in region are rectangles, the result is normalized by 
merging adjacent rectangles with banding done in the X direction. If it is :y- 
banding and all the regions in region are rectangles, the result is normalized with 
banding done in the Y direction. 



x-banding 



y— banding 



Normalizing a region set that is not composed entirely of rectangles using X- or 
Y-banding causes CLIM to signal the clim:region-set-not-rectangular error. 



clim:region-union regionl region2 



Generic Function 



Returns a region that contains all points that are in either regionl or region2 (pos- 
sibly with some points removed to satisfy the dimensionality rule). 

The result of clim:region-union always has dimensionality that is the maximum 
dimensionality of regionl and region2. For example, the union of a path and an 
area produces an area; the union of two paths is a path. 



clim:remove-command-from-command-table command-name command-table &key 
Oerrorp t) Function 

Removes the command named by command-name from the command table com- 
mand-table, command-table may be either a command table or a symbol that names 
a command table. 

If the command is not present in the command table and :errorp is t, the 
clim:command-not-present condition will be signalled. 



clim:remove-keystroke-from-command-table command-table keystroke &key Oer- 
rorp t) Function 

Removes the item named by keystroke from command-table's accelerator table, com- 
mand-table may be either a command table or a symbol that names a command ta- 
ble, keystroke is gesture spec, such as (:C : control : shift). 

If the command menu item associated with keystroke is not present in the com- 
mand table's menu and :errorp is t, then the clim:command-not-present condition 
will be signalled. 
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clim:remove-menu-item-from-command-table command-table string &key (:errorp 
t) Function 

Removes the item named by string from command-table's menu, command-table 
may be either a command table or a symbol that names a command table. 

If the command menu item is not present in the command table's menu and :er- 
rorp is t, then the clim:command-not-present condition will be signalled. 

This function ignores the character case of the command menu item's name when 
searching through the command table's menu. 



clim:repaint-sheet sheet region Generic Function 

Causes sheet and all of its descendants that overlap the region region to be re- 
painted, climrhandle-repaint is called to repaint each affected sheet. 

You can call this function when you want to redraw the whole hierarchy of panes 
that start at sheet. If you want to repaint only sheet, use the function climrhandle- 
repaint instead. 



climrreplace-input stream new-input &key .start :end -.rescan :buffer-start 

Generic Function 

Replaces stream's, input buffer with the string new-input, .start and send specify 
what part of new-input will be inserted into the buffer, and default to and the 
end of the string, respectively. 

.■buffer-start specifies where new-input should be inserted, and defaults to the cur- 
rent position in the input line. If rescan is t, a rescan operation will be queued; 
the default is nil. Usually, you should use the default values for :buffer-start and 
srescan, since the input editor automatically arranges for the correct behavior to 
occur under those circumstances. 

You can use this in an climraccept method that needs to replace some of the 
user's input by something else. For example, climrcomplete-input uses it to re- 
place partial input with the completed input. 

The returned value is the position in the input buffer. 

See the section "Utilities for climraccept Presentation Methods". See the section 
"The Structure of the CLIM Input Editor". 



climrreplay record stream &optional region Function 

Replays all of the output captured by the output record record on stream by calling 
climrreplay-output-record. If region is not nil, then record is replayed if and only 
if it overlaps region, region defaults to the intersection of stream's viewport and 
record's bounding rectangle. 

Changing the transformation of the stream during replaying has no effect on what 
is output by climrreplay. 
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climrreplay-output-record record stream &optional region x-offset y-offset 

Generic Function 

Replays all of the output captured by the output record record on stream. If region 
is not nil, then record is replayed if and only if it overlaps region. 

x-offset and y-offset are output record offsets that are necessitated by CLIM's repre- 
sentation of output records. In a later release of CLIM, the representation of out- 
put records may change in such a way that the x-offset and y-offset arguments are 
removed. 

Changing the transformation of the stream during replaying has no effect on what 
is output by climrreplay-output-record. 

You can specialize this generic function for your own classes of output records, but 
you should not generally call this function yourself. Any class that is a subclass of 
climrdisplayed-output-record must implement this method. 

Here is an example of using climrreplay-output-record in a way that supplies the 
X and Y offsets correctly: 

(multiple-value-bind (x-offset y-offset) 

(cl i m : convert- f rom-rel ati ve-to-absol ute-coordi nates 
stream (cl im: output-record-parent record)) 
(cl im: repl ay-output-record record stream region x-offset y-offset)) 



climrrescan-if-necessary input-editing-stream &optional inhibit-activation 

Generic Function 

Invokes a rescan operation on the input editing stream input-editing-stream if 
climrqueue-rescan was called on the same stream and no intervening rescan oper- 
ation has taken place. Resets the state of the "rescan queued" flag to nil. 

If inhibit-activation is nil, the input line will not be activated even if there is an 
activation gesture in it. 

You will rarely need to call this function yourself. Most programs should use 
climrqueue-rescan or climrimmediate-rescan instead. For more information on the 
input editor, see the section "The Structure of the CLIM Input Editor". 



climrreset-scan-pointer input-editing-stream &optional sp Generic Function 

Sets input-editing-stream's scan pointer to sp (which defaults to 0) and sets the 
state of climrstream-rescanning-p to t. 

You will rarely need to call this function yourself. For more information on the in- 
put editor, see the section "The Structure of the CLIM Input Editor". 



climrresize-sheet sheet width height Generic Function 

Changes the size of sheet to have width width and height height. 
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clim:resize-sheet works by modifying the sheet's region, and could be implemented 
as follows: 

(defmethod cl im: resize-sheet 

((sheet cl im: basic-sheet) width height) 
(setf (cl im:sheet-region sheet) 

(cl im:make-bounding-rectangle width height))) 

You should not generally use this function to resize a sheet, because it does not 
interact directly with the frame layout protocol. That is, resizing a sheet with 
clim:resize-sheet may appear not to have any effect until you invoke the entire 
layout protocol. If you need to resize a top-level sheet, use clim:size-frame-from- 
contents. 



clim:restart-port port Generic Function 

Restarts the event process that handles the port port. 

Occasionally the event process that handles a port may hang for some reason, al- 
though this is rather uncommon. Symptoms that this has happened include lack of 
pointer highlighting, and no echoing of typein. In the event that this happens, you 
can call clim:restart-port to restart the event process. 

clim-sys:restart-process process Function 

Restarts the process process by "unwinding" it to its initial state, and reinvoking 
its top-level function. 

clim:rigid-transformation-p transform Generic Function 

Returns t if transform transforms the coordinate system as a rigid object, that is, 
as a combination of translations, rotations, and pure reflections. Otherwise, it re- 
turns nil. 

Rigid transformations are the most general category of transformations that pre- 
serve magnitudes of all lengths and angles. 

clim:r-tree-output-history Class 

A standard class provided by CLIM for use as a top-level output history. This is a 
subclass of both clim:r-tree-output-record and clim:stream-output-history-mixin. 

You should consider using this as the output history for any pane that will have 
lots of overlapping output records, such as a complex graphical editor. You can 
create a pane using this history class as follows: 

(cl im:make-cl im-appl i cation-pane 

: output-record (make-instance 'cl im: r-tree-output-history)) 
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clim:r-tree-output-record Class 

CLIM provides this output record class to store sequences of output records that 
tend to overlap a great deal. The ordering of the tree is based on all four corners 
of the bounding rectangles of the records contained in it. 

The insertion and retrieval complexity of this class is O(log n), but the overhead is 
fairly high. However, this output record class maintains temporal ordering (that is, 
stacking) very well. 



clim:run-frame-top-level frame &key &allow-other-keys Generic Function 

Runs the top-level function for frame. The default method merely runs the top- 
level function of frame as specified by the :top-level option of climrdefine- 
application-frame. If no :top-level was specified, clim:default-frame-top-level is 

used. 

The returned values are the values returned by the top level function of frame. 

clim:application-frame provides an raround method which binds 
clim:*application-frame* to frame. 



clim:scaling-transformation-p transform Generic Function 

Returns t if transform multiplies all X-lengths by one magnitude and all Y-lengths 
by another magnitude, otherwise returns nil. This category includes even scalings 
as a subset. 



clim:scroll-bar Class 

The clim:scroll-bar gadget class corresponds to a scroll bar. It is a subclass of 
climrvalue-gadget, clim:oriented-gadget-mixin, and clim:range-gadget-mixin. 

In addition to the initargs for climrvalue-gadget and the usual pane initargs 
(rforeground, rbackground, space requirement options, and so forth), the following 
initargs are supported: 

rorientation 

Either rvertical or rhorizontal. 

rdrag-callback 

Specifies the callback to be invoked when the scroll bar indicator is 
dragged. 

:scroll-to-bottom-callback 

Specifies the callback to be invoked when the scroll bar will scroll 
to the bottom of the viewport. 

:scroll-to-top-callback 

Specifies the callback to be invoked when the scroll bar will scroll 
to the top of the viewport. 
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:scroll-down-line-callback 

Specifies the callback to be invoked when the scroll bar will scroll 
down one line. 

:scroll-up-line-callback 

Specifies the callback to be invoked when the scroll bar will scroll 
up one line. 

:scroll-down-page-callback 

Specifies the callback to be invoked when the scroll bar will scroll 
down one page. 

:scroll-up-page-callback 

Specifies the callback to be invoked when the scroll bar will scroll 
up one page. 

The climrvalue-changed-callback is invoked only after the indicator is released af- 
ter dragging it. 

Calling clim:gadget-value on a scroll bar will return a real number within the 
specified range of the scroll bar, usually between and 1 (inclusive). 



climrscroll-extent sheet x y Generic Function 

If the pane sheet is part of a scroller pane, this scrolls the pane in its viewport so 
that the position (x,y) of sheet is at the upper-left corner of the viewport. Other- 
wise, it does nothing. 

climrscroll-extent, and all other functions that change the position of the viewport, 
also call climrnote-viewport-position-changed to notify the sheet that it has been 
scrolled. 

You can specialize climrscroll-extent when you want to implement new scrolling 
behavior for a sheet. If you want to simply do something in addition to the normal 
scrolling behavior, you should specialize climrnote-viewport-position-changed in- 
stead. 



climrscrolling f&rest options) &body contents Macro 

Creates a composite pane that allows the single child specified by contents to be 
scrolled, options may include a rscroll-bar option. The value of this option may be 
t (the default), which indicates that both horizontal and vertical scroll bars should 
be created; rvertical, which indicates that only a vertical scroll bar should be cre- 
ated; rhorizontal, which indicates that only a horizontal scroll bar should be cre- 
ated; or mone, which indicates that the pane is scrollable but will have no visible 
scroll bars. 

The pane created by the climrscrolling macro is a composite pane that includes a 
"scroller pane". The "scroller pane" has as children the scroll bars and a "view- 
port pane". The viewport of a pane is the portion of the window's drawing plane 
that is currently visible to the user. The viewport has as its child the specified 
contents. 
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clim:select-file frame &key .-default .-associated-window .-title -.exit-boxes -.text-style 
-.foreground -.background :x-position :y-position Generic Function 

Pops up a file selection dialog in order to input a pathname from the user. The 
default pathname is specified by .-default. The returned value is the pathname. 

.-associated-window is the window with which the notification is associated, .-title is 
a string used to label the notification, -.exit-boxes is as for climraccepting-values. 

-.text-style, -.foreground, and -.background are the text style, foreground ink, and 
background ink to use in the notification window. :x-position and :y-position can be 
supplied to position the notification window. 



sequence type Clim Presentation Type 

The presentation type that represents a sequence of elements of type type. The 
printed representation of a sequence type is the elements separated by the separa- 
tor character. It is unspecified whether climraccept returns a list or a vector. You 
can specify the following options: 

rseparator The character that separates members of the set of possibili- 
ties in the printed representation when there is more than one. 
The default is comma (#\,). 

:echo-space If this is t, then CLIM will insert a space automatically after 
the separator, otherwise it will not. The default is t. 

type can be a presentation type abbreviation. 



climrsequence-enumerated &rest types Clim Presentation Type 

climrsequence-enumerated is like sequence, except that the type of each element 
in the sequence is individually specified. It is unspecified whether climraccept re- 
turns a list or a vector. You can specify the following options: 

rseparator The character that separates members of the set of possibili- 
ties in the printed representation when there is more than one. 
The default is comma (tt\, ). 

recho-space If this is t, then CLIM will insert a space automatically after 
the separator, otherwise it will not. The default is t. 

The elements of types can be presentation type abbreviations. 



climrset-highlighted-presentation stream presentation &optional (prefer-pointer- 
window t) Function 

Highlights the presentation presentation on stream. If presentation is nil, any high- 
lighted presentations are unhighlighted. 
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If prefer-pointer-window is t (the default), this sets the highlighted presentation for 
the window that is located under the pointer. Otherwise it sets the highlighted 
presentation for the window stream. 



climrsheet Class 

The protocol class that corresponds to a sheet. If you want to create a new class 
that obeys the sheet protocol, it must be a subclass of climrsheet. 



climrsheet-adopt-child sheet child Generic Function 

Adds the child sheet child to the set of children of sheet, and makes the sheet the 
child's parent. If child already has a parent, CLIM will signal an error. 

Some sheet classes support only a single child. For such sheets, attempting to 
adopt more than a single child will cause CLIM to signal an error. 

See the section "Sheet Relationship Protocols". 

climrsheet-children sheet Generic Function 

Returns a list of all of the sheets that are children of sheet. 

climrsheet-children may cons a new list each time it is called. It may be more ef- 
ficient to use climrmap-over-sheets instead of climrsheet-children. 

See the section "Sheet Relationship Protocols". 

climrsheet-device-region sheet Generic Function 

Returns a region object that describes the region that sheet occupies on the display 
device. The coordinates are in the host's native window coordinate system. 

The device region is usually an instance of climrstandard-bounding-rectangle. 

Note that the region object returned by this function is volatile, so you must not 
depend on the components of the object remaining constant. 



climrsheet-device-transformation sheet Generic Function 

Returns a transformation that converts coordinates in sheet's coordinate system in- 
to native coordinates on the display device. 

Note that the transformation object returned by this function is volatile, so you 
must not depend on the components of the object remaining constant. 



climrsheet-disown-child sheet child &key (:errorp t) Generic Function 

Removes the child sheet child from the set of children of sheet, and makes the par- 
ent of the child be nil. If child is not actually a child of sheet and :errorp is t, 
then an error will be signalled. 
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See the section "Sheet Relationship Protocols". 

clim:sheet-enabled-p sheet Generic Function 

Returns t if sheet is enabled by its parent, otherwise returns nil. 

You can used setf on this in order to enable or disable a sheet. 

In order for a sheet to be enabled and "viewable", all of a sheet's ancestors must 
be enabled and "viewable" as well. 

clim:sheet-event-queue sheet Generic Function 

Any sheet that can process events will have an event queue from which the events 
are gotten. clim:sheet-event-queue returns the object that acts as the event 
queue. 

Typically, you will only use this function in order to cause one or more sheets to 
share the same event queue. For example, you can cause a window created with 
climropen-window-stream to share the event queue of another frame as follows: 

(setf (cl im: sheet-event-queue window) 
(cl im : sheet-event-queue 

(cl im : f rame-top-1 evel -sheet frame) ) ) 

See the section "Sheet Input Protocols". 

climrsheet-medium sheet Generic Function 

Returns the medium associated with sheet. If sheet does not have a medium allocat- 
ed to it, climrsheet-medium returns nil. 

This function will signal an error if sheet does not support doing output. 

See the section "Sheet Output Protocols". 

climrsheet-mirror sheet Generic Function 

Returns the host window that is used to display sheet. 

Note that this will nearly always return the same result as calling climrmedium- 
drawable on climrsheet-medium of sheet. 

climrsheet-parent sheet Generic Function 

Returns the sheet that is the parent of sheet, or nil if sheet has no parent. 

climrsheet-pointer-cursor sheet Generic Function 
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Returns the type of cursor that will be used for the pointer when the pointer is 
over sheet. 

The valid cursor types are rdefault, rvertical-scroll, :scroll-up, :scroll-down, 
rhorizontal-scroll, :scroll-left, :scroll-right, :busy, :upper-left, :upper-right, 
:lower-left, :lower-right, : vertical-thumb, :horizontal-thumb, rbutton, rprompt, 
move, rposition, and :i-beam. 

You can use setf on climrsheet-pointer-cursor to change the cursor type. 



climrsheet-region sheet Generic Function 

Returns a region object that represents the set of points to which sheet refers. The 
region is usually a bounding rectangle object. Its coordinates are in the sheet's co- 
ordinate system (that is, the upper left corner of the region will typically be at 
(0,0)). 

The region is usually an instance of climrstandard-bounding-rectangle. 

You can use setf on this to change the sheet's region, although it is generally 
preferable to use clim:resize-sheet instead. When you change a sheet's region, 
CLIM will call clim:note-sheet-region-changed sheet to notify the sheet of the 
change. 

See the section "Sheet Geometry Protocols". 



climrsheet-transformation sheet Generic Function 

Returns a transformation that converts coordinates in sheet's coordinate system in- 
to coordinates in its parent's coordinate system. 

You can use setf on this to change the sheet's transformation, although it is gen- 
erally preferable to use clim:move-sheet instead. When you change a sheet's re- 
gion, CLIM will call clim:note-sheet-transformation-changed sheet to notify the 
sheet of the change. 

See the section "Sheet Geometry Protocols". 



climrsheetp object Generic Function 

Returns t if and only if object is of type climrsheet, otherwise returns nil. 

clim:+shift-key+ Constant 

The modifier state bit that corresponds to the user holding down the shift key on 
the keyboard. 

clim:simple-parse-error Condition 
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This condition is signalled when CLIM does not know how to parse some sort of 
user input while inside of climraccept. It is built on conditions:parse-error. 



clim:simple-parse-error format-string &rest format-arguments Function 

Signals an error of type clim:simple-parse-error. This can be called while parsing 
an input token, for example, by a method on climraccept. This function does not 
return. 



climrsingular-transformation Condition 

The condition that is signalled when you try to invert a singular (non-invertible) 
transformation. 



clim:size-frame-from-contents stream &key -.width -.height (-.right-margin 10) (-.bot- 
tom-margin 10) (-.size-setter #'clim:window-set-inside-sizeJ Function 

This function resizes the frame that contains the pane stream to have the size 
-.width and -.height. If -.width and -.height are not supplied, they are computed by 
taking the size of the output contained within stream. The width and height are 
incremented by -.right-margin and -.bottom-margin. 

This function is intended to be called on streams that are the only pane in their 
parent frame. For example, CLIM uses this function to properly size pop-up menus 
and own-window dialogs. 



climrslider Class 

The climrslider gadget class corresponds to a slider. It is a subclass of climrvalue- 
gadget, climroriented-gadget-mixin, climrrange-gadget-mixin, and climrlabelled- 
gadget-mixin. 

See the section "Using Gadgets in CLIM". 

In addition to the initargs for climrvalue-gadget and the usual pane initargs 
(rforeground, rbackground, rtext-style, space requirement options, and so forth), 
the following initargs are supported: 

rorientation 

Specifies the orientation of the slider, either rhorizontal or 
rvertical. The default is rhorizontal. 

rdrag-callback 

Specifies the drag callback for the slider. 

rshow-value-p 

Whether the slider should show its current value. The default is 
nil. 
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: decimal-places 

An integer that specifies the number of decimal places that should 
be shown if the current value is being shown. The default is to 
show all significant digits. 

:min-label 

A string to use to label the minimum end of the slider. By default, 
there is no min label. 

:max-label 

A string to use to label the maximum end of the slider. By default, 
there is no max label. 

:range-label-text-style 

The text style to use for the min and max labels. 

:number-of-tick-marks 

The number of tick marks to draw on the slider. By default, there 
are no tick marks on the slider. 

:number-of-quanta 

Either nil (the default) or an integer. If an integer, specifies the 
number of "quanta" in the slider. In this case the slider is not 
continuous, and can only assume a value that falls on one of the 
"quanta". For example, a slider for real numbers will not be quan- 
tized, whereas a slider for integers will be quantized. 

The climrdrag-callback callback is invoked when the value of the slider is 
changed while the indicator is being dragged. This is implemented by calling the 
function specified by the :drag-callback initarg with two arguments, the slider 
and the new value. 

The climrvalue-changed-callback is invoked only after the indicator is released af- 
ter dragging it. 

Calling clim:gadget-value on a slider will return a real number within the speci- 
fied range of the slider. 

Here are some examples of sliders: 

(cl im: make-pane 'cl im:sl ider 
: label "A si ider" 

: value-changed-cal lback 'si ider-changed-cal lback 
:drag-cal lback 'si ider-dragged-cal lback) 

(cl im: make-pane 'cl im:sl ider 

:label "A slider with tick marks and range labels" 

:number-of-tick-marks 20 

:min-label "0" :max-label "20" 

: value-changed-cal lback 'si ider-changed-cal lback 

:drag-cal lback 'si ider-dragged-cal lback) 
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(cl im: make-pane 'cl im:sl ider 

:label "A vertical slider with visible value" 
:orientation :vertical 
:show-value-p t) 



(cl im: make-pane 'clim:slider 

:label "A very hairy quantized slider" 

:orientation :vertical 

:number-of-tick-marks 20 

:number-of-quanta 20 

:show-value-p t 

:min-value :max-value 20 

:min-label "Min" :max-label "Max" 

: value-changed-cal lback 'si ider-changed-cal lback 

:drag-cal lback 'si ider-dragged-cal lback) 



(defun si ider-changed-cal lback (slider value) 

(format t "~&Slider ~A changed to ~S" (cl im: gadget-label slider) value)) 

(defun si ider-dragged-cal lback (slider value) 

(format t "~&Slider ~A dragged to ~S" (cl im: gadget-label slider) value)) 



clim:slider-view 



Class 



The class that represents the view corresponding to a slider. This is usually used 
for fields that represent a continuous range of values (such as a bounded range of 
real numbers). 



clim:+slider-view+ 

An instance of the class clim:slider-view. 



Constant 



climrspace-requirement 



Class 



The object that specifies a pane's desired width and height, as well as the amount 
it is willing to shrink or grow along its width and height. 



clim:space-requirement+ space-req 



Function 



Returns a new space requirement whose components are the sum of each of the 
components of srl and sr2. 



climrspace-requirement-components space-req 



Function 
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Returns the components of the space requirement space-req as six values, the 
width, minimum width, maximum width, height, minimum height, and maximum 
height. 



climrspacing f&rest options &key .-thickness .-background &allow-other-keys) &body 
contents Macro 

The climrspacing reserves some margin space around a single child pane, .-thick- 
ness specifies the amount of space in device units, and .-background specifies the 
ink to be used as the pane's background (that is, the color of the margin space). 
contents is a form that produces a single pane. 

The climrspacing macro is the usual way of creating a pane of type climrspacing- 
pane. 

options may include other pane initargs, such as space requirement options, 
rforeground, rbackground, rtext-style, and so forth. 



climrspacing-pane Class 

The layout pane class that leaves some empty space around its child pane. 
climrspacing generates a pane of this type. 

In addition to the usual sheet initargs (the space requirement initargs, 
rforeground and rbackground), this class supports two other initargs: 

rthickness 

An integer that specifies the amount of space to leave around the 
child pane, in device units. 

rcontents The pane that will be the child. 



climr*standard-activation-gestures* Variable 

A list of gesture names that cause the current input to be activated. On most sys- 
tems, this includes the gestures corresponding to the tt\Neul-ine (or ttsReturn) 
characters. On Genera, it includes the gesture for the tt\End character as well. 



climrstandard-application-frame Class 

This is the class on which all standard CLIM application frames are based. 

Typically when you make a new class of application frame, it should inherit from 
climrstandard-application-frame. If you do not explicitly supply any superclasses 
in a climrdefine-application-frame form, CLIM will arrange for the new frame 
class to inherit from climrstandard-application-frame. 

climrstandard-bounding-rectangle Class 
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The standard instantiable class for bounding rectangles in CLIM. All of CLIM's 
output record classes are built on climrstandard-bounding-rectangle. 



climrstandard-ellipse Class 

The standard class CLIM uses to implement an ellipse. This is a subclass of 
climrellipse. This is the class that climrmake-ellipse and climrmake-ellipse* in- 
stantiate. 



clim:standard-elliptical-arc Class 

The standard class CLIM uses to implement an elliptical arc. This is a subclass of 
clim:elliptical-arc. This is the class that clim:make-elliptical-arc and climrmake- 
elliptical-arc* instantiate. 



clim:standard-line Class 

The standard class CLIM uses to implement lines. This is a subclass of climrline. 
This is the class that clim:make-line and climrmake-line* instantiate. 



clim:standard-point Class 

The standard class CLIM uses to implement points. This is the class that 
clim:make-point instantiates. 



climrstandard-polygon Class 

The standard class CLIM uses to implement polygons. This is a subclass of 
climrpolygon. 

This is the class that climrmake-polygon and climrmake-polygon* instantiate. 



climrstandard-polyline Class 

The standard class CLIM uses to implement polylines. This is a subclass of 
climrpolyline. This is the class that climrmake-polyline and climrmake-polyline* 

instantiate. 



climrstandard-presentation Class 

The standard class used by CLIM to represent presentations. By default, 
climrpresent and clim:with-output-as-presentation create presentations using this 
class. 



climrstandard-rectangle Class 
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The standard class CLIM uses to implement rectangles. This is a subclass of 
climrrectangle. This is the class that climrmake-rectangle and climrmake- 
rectangle* instantiate. 



climrstandard-sequence-output-history Class 

A standard class provided by CLIM for use as a top-level output history. This is a 
subclass of both climrstandard-sequence-output-record and climrstream-output- 
history-mixin. 



climrstandard-sequence-output-record Class 

The standard class provided by CLIM to store a relatively short sequence of output 
records; a subclass of climroutput-record. 

The insertion and retrieval complexity of this class is O(n). Most of the formatted 
output facilities (such as clim:formatting-table) create output records that are a 
subclass of climrstandard-sequence-output-record. 



clim:standard-tree-output-history Class 

The class used by CLIM as the default top-level output history. This is a subclass 
of both clim:standard-tree-output-record and clim:stream-output-history-mixin. 



clim:standard-tree-output-record Class 

The standard class provided by CLIM to store longer sequences of output records. 
The child records of a tree output record area maintained in a sorted order, based 
on the lexicographic ordering on the X and Y coordinates of the children. 

The insertion and retrieval complexity of this class is O(log n), but it is highly op- 
timized for doing textual-style output where most new output comes at the end 
(lower right) of the record. 



clim:stream-add-output-record stream record Generic Function 

Adds the new output record record to stream's current output record (that is, 
climrstream-current-output-record). This also takes care of other bookkeeping, 
such as adjusting stream's scroll bars if the stream supports scrolling. 



climrstream-baseline stream Generic Function 

Returns the current text baseline for the stream stream. 

clim:stream-character-width stream character &optional text-style Generic Function 
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Returns the horizontal motion of the cursor position that would occur if this char- 
acter were output onto stream in the text style text-style, climrstream-character- 
width does not take into account the value of clim:stream-text-margin when com- 
puting the size of the output. 

text-style defaults to the stream's current text style. The answer depends on the 
current cursor position when the character is ttMab or ttsNeul ine. 



clim-lisp: stream-clear-input stream Generic Function 

Clears all pending input from stream's input buffer. 

In CLIM, clear-input is implemented by call clim-lisp:stream-clear-input. 

climrstream-current-output-record stream Generic Function 

The current "open" output record for the output recording stream stream, that is, 
the one to which clim:stream-add-output-record will add a new child record. Ini- 
tially, this is the same as climrstream-output-history. As applications created 
nested output records, this acts as a stack of open output records. 

climrstream-cursor-position stream Generic Function 

Returns two values, the X and Y coordinates of the cursor position on the drawing 
plane. You can use clim:stream-set-cursor-position or climrstream-increment- 
cursor-position to change the cursor position. 

clim:stream-default-view stream Generic Function 

Returns the default view for the stream stream. You can change the default view 
for a stream by using setf on clim:stream-default-view. Calls to climraccept de- 
fault the :view argument from clim:stream-default-view. 

Many CLIM streams will have the textual view, clim:+textual-view+, as their de- 
fault view. Inside of climrmenu-choose, the default view will be clim:+textual- 
menu-view+. Inside of climraccepting-values, the default view will be either 
clim:+textual-dialog-view+ or clim:+gadget-dialog-view+. 

clim:stream-drawing-p stream Generic Function 

Returns t if and only if drawing is enabled on the output recording stream stream. 
You can use setf on this to enable or disable drawing on the stream, or you can 
use the :draw option to climrwith-output-recording-options. 

clim:stream-element-type stream Generic Function 

In CLIM, stream-element-type is defined as a generic function. Otherwise, it be- 
haves the same as the normal Common Lisp stream-element-type function. 
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clim:stream-end-of-line-action stream Generic Function 

Controls what happens when the cursor position moves horizontally out of the 
viewport (beyond the text margin). You can use setf on this to change the end of 
line action. 

The possible values for clim:stream-end-of-line-action are: 

:wrap When doing text output, wrap the text around (that is, break 
the text line and start another line). When setting the cursor 
position, scroll the window horizontally to keep the cursor posi- 
tion inside the viewport. This is the default. 

rscroll Scroll the window horizontally to keep the cursor position in- 
side the viewport, then keep doing output. 

rallow Ignore the text margin and just keep doing output. 

You can use clim:with-end-of-line-action to temporarily change the end-of-line ac- 
tion. 



clim:stream-end-of-page-action stream Generic Function 

Controls what happens when the cursor position moves vertically out of the view- 
port. You can use setf on this to change the end of page action. 

The possible values for clim:stream-end-of-page-action are: 

rscroll Scroll the window vertically to keep the cursor position inside 
the viewport, then keep doing output. This is the default. 

rallow Ignore the viewport and just keep doing output. 

rwrap Wrap the text around (that is, go back to the top of the view- 
port). This is not currently implemented. 

You can use climrwith-end-of-page-action to temporarily change the end-of-page 
action. 



clim-lispr stream-finish-output stream Generic Function 

Some streams are implemented in an asynchronous, or buffered, manner, clim- 
lispr stream-finish-output attempts to ensure that all output sent to stream has 
reached its destination, and only then returns nil. 

In CLIM, finish-output is implemented by calling clim-lisprstream-finish-output. 



clim-lispr stream-force-output stream Generic Function 

Some streams are implemented in an asynchronous, or buffered, manner, clim- 
lispr stream-force-output initiates the emptying of any internal buffers, and re- 
turns nil without waiting for completion or acknowledgment. 
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In CLIM, force-output is implemented by calling clim-lisp:stream-force-output. 



clim-lisp: stream-fresh-line stream Generic Function 

Outputs a newline only if stream is not already at the start of a line. If for any 
reason this cannot be determined, then a newline is output anyway. This guaran- 
tees that the stream will be on a fresh line while consuming as little vertical 
space as possible. 

In CLIM, fresh-line is implemented by calling clim-lisp:stream-fresh-line. 



climrstream-increment-cursor-position stream dx dy Generic Function 

Moves the cursor position on stream relatively, adding dx to the X coordinate and 
adding dy to the Y coordinate. Either argument dx or dy can be nil, which means 
not to change that coordinate. 



clim:stream-input-wait stream &key -.timeout :input-wait-test Generic Function 

Waits until .-timeout has expired or :input-wait-test returns a non-nil value. Other- 
wise the function waits until there is input in the stream. 

.-timeout Specifies the number of seconds that clim:stream-input-wait 

will wait for input to become available. If no input is available 
when the timeout expires, clim:stream-input-wait will return 
the two values nil and rtimeout. If nil (the default), it will 
wait indefinitely. 

:input-wait-test The value of this argument is a function. The function will be 

invoked with one argument, the stream. If the function returns 
nil, clim:stream-input-wait will continue to wait for user in- 
put. If it returns t, clim:stream-input-wait will return the two 
values nil and :input-wait-test. 



climrstream-insertion-pointer input-editing-stream Generic Function 

Returns an integer corresponding to the current input position of input-editing- 
stream, that is, the point in the buffer at which the next user input gesture will 
be inserted. The insertion pointer will always be less than (fill-pointer 
(clim:stream-input-buffer stream)). The insertion pointer is used as the location of 
the editing cursor. 

You can use setf on climrstream-insertion-pointer to change the insertion pointer. 

For more information on the input editor, see the section "The Structure of the 
CLIM Input Editor". 



clim:stream-line-height stream &optional text-style Generic Function 
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Returns what the line height of a line containing text in that text-style would be. 
text-style defaults to (clim:medium-text-style stream). 



clim-lisp: stream-listen stream Generic Function 

Returns t if there is input available on stream, nil if not. 

In CLIM, listen is implemented by calling clim-lisp: stream-listen. 

climrstream-output-history stream Generic Function 

Returns the top level output record for the stream stream. 

clim-lisp: stream-peek-char stream Generic Function 

Returns the next character available in the input stream. The character is not re- 
moved from the input buffer. Thus, the same character will be returned by a sub- 
sequent call to clim-lisp:stream-read-char. 

In CLIM, peek-char is implemented by calling clim-lisp:stream-peek-char. 

climrstream-pointer-position stream &key .-pointer Generic Function 

This function returns the position (two coordinate values) of the .-pointer in the 
stream's drawing plane coordinate system. If .-pointer is not supplied, the default 
pointer for stream's port is used. 

You can use clim:stream-set-pointer-position to set the pointer position. 
Manipulating the Pointer in CLIM 

Concepts of Manipulating the Pointer in CLIM 

A pointer is an input device that enables pointing at an area of the screen (for 
example, a mouse, or a a tablet). CLIM offers a set of operators that enable you to 
manipulate the pointer. 

Operators for Manipulating the Pointer in CLIM 

These functions are the higher-level functions for doing input via the pointer. 

climrtracking-pointer f&optional stream &key .-pointer .-multiple-window itransformp 
(-.context-type t) .-highlight) &body clauses 

Provides a general means for running code while following the position 
of a pointing device, and monitoring for other input events. Programmer- 
supplied code may be run upon occurrence of events such as motion of 
the pointer, clicking of a pointer button, or typing something on the 
keyboard. 
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climrdrag-output-record stream output-record &key (.-repaint t) .-multiple-window 
.-erase .-feedback (:finish-on-release t) 

Enters an interaction mode in which user moves the pointer, and output- 
record follows the pointer by being dragged on stream. 

climrdragging-output f&optional stream &key (.-repaint t) .-multiple-window -.finish- 
on-release) &body body 

Evaluates body to produce the output, and then invokes climrdrag- 
output-record to drag that output on stream. 

clim:pointer-place-rubber-band-line* &key :start-x :start-y (stream *standard- 
input*) .-pointer .-multiple-window (:finish-on-release t) 
Prompts for a line via the pointing device specified by .-pointer. 
clim:pointer-place-rubber-band-line* returns four values, the start-x, 
start-y, end-x, and end-y of a line. 

climrpointer-input-rectangle* &key deft stop .-right .-bottom (stream *standard- 
input*) .-pointer .-multiple-window (:finish-on-release t) 
Prompts for a rectangular area via the pointing device specified by 
.-pointer. climrpointer-input-rectangle* returns four values, the left, top, 
right, and bottom edges of a rectangle. 

The following are lower level functions for managing the pointer more directly. 

See the generic function climrstream-pointer-position. 

clim:stream-set-pointer-position stream x y &key .-pointer 

This function sets the position (two coordinate values) of the .-pointer in 
the stream's drawing plane coordinate system. 

climrport-pointer port 

Returns the pointer object corresponding to the primary pointing device 
for the port port. 

clim:port-modifier-state basic-port 

Returns the state of the modifier keys for the port port. 

clim:pointer-button-state pointer 

Returns the current button state for pointer. 

climrpointer-position pointer 

This function returns the position (as two coordinate values) of the 
pointer pointer in the coordinate system of the sheet that the pointer is 
currently over. 

clim:pointer-set-position pointer x y 

This function changes the position of the pointer pointer to be (x,y). 

climrpointer-native-position pointer 

This function returns the position (as two coordinate values) of the 
pointer pointer in the coordinate system of the port's graft (that is, its 
"root window"). 
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clim:pointer-set-native-position pointer x y 

This function changes the position of the pointer pointer to be (x,y). 

clim:pointer-sheet pointer 

Returns the sheet over which the pointer pointer is currently positioned. 

climrpointer-cursor pointer 

Returns the current cursor type for pointer. You can use setf to change 
it. 



clim:stream-recording-p stream Generic Function 

Returns t if and only if output recording is enabled on the output recording 
stream stream. You can use setf on this to enable or disable output recording on 
the stream, or you can use the rrecord option to climrwith-output-recording- 
options. 



clim-lisp: stream-read-char stream Generic Function 

Returns the next character available in the input stream. If no character is avail- 
able, this function will wait until one becomes available. 

In CLIM, read-char is implemented by calling clim-lisp:stream-read-char. Note 
that, unlike read-char, clim-lisp: stream-read-char does not echo the character it 
reads; CLIM's input editor does this when reading input inside of a call to 
clim:with-input-editing. 



clim-lisp: stream-read-char-no-hang stream Generic Function 

Like clim-lisp: stream-read-char except that if no character is available the func- 
tion returns nil. 

In CLIM, read-char-no-hang is implemented by calling clim-lisp: stream-read- 
char-no-hang. 



clim:stream-read-gesture stream &key .-timeout :peek-p :input-wait-test :input-wait- 
handler :pointer-button-press-handler Generic Function 

Returns the next gesture available in the input stream. The arguments are as for 
clim:read-gesture. Note that clim:stream-read-gesture does not echo its input; 
CLIM's input editor does this when reading input inside of a call to clim:with- 
input-editing. 

This function invokes clim:stream-input-wait on the stream and processes the 
subsequent input, if any. CLIM's input editor is implemented by specializing 
clim:stream-read-gesture to process input editing commands. 

clim:read-gesture is implemented by calling clim:stream-read-gesture. This func- 
tion is a generalization of clim-lisp: stream-read-char to extended input streams. 
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clim-lisp: stream-read-line stream Generic Function 

Returns a string containing a line of text, delimited by the tt\Neul-ine character. 
In CLIM, read-line is implemented by calling clim-lisp:stream-read-line. 

climrstream-replay stream &optional region Generic Function 

Replays all of the output records in stream's output history that overlap the region 
region. If region is nil, all of the output records are replayed. 

clim:stream-rescanning-p input-editing-stream Generic Function 

Returns the state of the input editing stream's "rescan in progress" flag, which is 
t if input-editing-stream is performing a rescan operation, otherwise it is nil. Non- 
input editing streams always return nil. 

For more information on the input editor, see the section "The Structure of the 
CLIM Input Editor". 

clim:stream-scan-pointer input-editing-stream Generic Function 

Returns the current scan pointer (an integer) for input-editing-stream, that is, the 
point in the buffer at which calls to climraccept have stopped parsing input. The 
scan pointer will always be less than or equal to climrstream-insertion-pointer of 
input-editing-stream. 

The next call to climrread-gesture on input-editing-stream will return the gesture 
at the scan pointer. 

You can use setf on clim:stream-scan-pointer to change the scan pointer. 

For more information on the input editor, see the section "The Structure of the 
CLIM Input Editor". 

clim:stream-set-cursor-position stream x y Generic Function 

Moves the cursor position to the specified X and Y coordinates on the drawing 
plane. 

clim:stream-set-input-focus stream Generic Function 

Gives the input focus to stream, and returns as a value the stream or sheet that 
previously had the input focus. 

clim:stream-set-pointer-position stream x y &key -.pointer Generic Function 

This function sets the position (two coordinate values) of the pointer in the 
stream's drawing plane coordinate system (if possible). If not possible, the function 
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leaves the pointer where it was. If .-pointer is not supplied, the pointer for stream's 
port is used. 

Be careful when you use this function. It is often best to avoid creating user inter- 
faces where the pointer jumps around unexpectedly. 



Manipulating the Pointer in CLIM 



Concepts of Manipulating the Pointer in CLIM 

A pointer is an input device that enables pointing at an area of the screen (for 
example, a mouse, or a a tablet). CLIM offers a set of operators that enable you to 
manipulate the pointer. 



Operators for Manipulating the Pointer in CLIM 

These functions are the higher-level functions for doing input via the pointer. 

climrtracking-pointer f&optional stream &key .-pointer .-multiple-window itransformp 
( context-type t) .-highlight) &body clauses 

Provides a general means for running code while following the position 
of a pointing device, and monitoring for other input events. Programmer- 
supplied code may be run upon occurrence of events such as motion of 
the pointer, clicking of a pointer button, or typing something on the 
keyboard. 

climrdrag-output-record stream output-record &key (.-repaint t) .-multiple-window 
.-erase .-feedback (:finish-on-release t) 

Enters an interaction mode in which user moves the pointer, and output- 
record follows the pointer by being dragged on stream. 

climrdragging-output f&optional stream &key (.-repaint t) .-multiple-window -.finish- 
on-release) &body body 

Evaluates body to produce the output, and then invokes climrdrag- 
output-record to drag that output on stream. 

clim:pointer-place-rubber-band-line* &key :start-x :start-y (stream *standard- 
input*) .-pointer .-multiple-window (:finish-on-release t) 
Prompts for a line via the pointing device specified by .-pointer. 
clim:pointer-place-rubber-band-line* returns four values, the start-x, 
start-y, end-x, and end-y of a line. 

climrpointer-input-rectangle* &key deft stop .-right .-bottom (stream *standard- 
input*) .-pointer .-multiple-window (:finish-on-release t) 
Prompts for a rectangular area via the pointing device specified by 
.-pointer. climrpointer-input-rectangle* returns four values, the left, top, 
right, and bottom edges of a rectangle. 

The following are lower level functions for managing the pointer more directly. 
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climrstream-pointer-position stream &key .-pointer 

This function returns the position (two coordinate values) of the pointer 
in the stream's drawing plane coordinate system. You can use 
clim:stream-set-pointer-position to set the pointer position. 

See the generic function clim:stream-set-pointer-position. 

climrport-pointer port 

Returns the pointer object corresponding to the primary pointing device 
for the port port. 

clim:port-modifier-state basic-port 

Returns the state of the modifier keys for the port port. 

clim:pointer-button-state pointer 

Returns the current button state for pointer. 

climrpointer-position pointer 

This function returns the position (as two coordinate values) of the 
pointer pointer in the coordinate system of the sheet that the pointer is 
currently over. 

clim:pointer-set-position pointer x y 

This function changes the position of the pointer pointer to be (x,y). 

climrpointer-native-position pointer 

This function returns the position (as two coordinate values) of the 
pointer pointer in the coordinate system of the port's graft (that is, its 
"root window"). 

clim:pointer-set-native-position pointer x y 

This function changes the position of the pointer pointer to be (x,y). 

clim:pointer-sheet pointer 

Returns the sheet over which the pointer pointer is currently positioned. 

climrpointer-cursor pointer 

Returns the current cursor type for pointer. You can use setf to change 
it. 



clim:stream-string-width stream string &key .start send :text-style Generic Function 

Computes how the cursor position would move horizontally if the specified string 
were output starting at the left margin. clim:stream-string-width does not take 
into account the value of clim:stream-text-margin when computing the size of the 
output. 

The first value is the X coordinate the cursor position would move to. The second 
value is the maximum X coordinate the cursor would visit during the output. (This 
is the same as the first value unless the string contains a ttsNeul ine.) 

-.start and send default to and the length of the string, respectively. 
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:text-style defaults to the stream's current text style. 

Note that clim:stream-string-width is a low level function. Unless you are writing 
your own "formatting engine", if you find you need to use it very often, you may 
be working at too low a level of abstraction. 



clim-lisp:stream-terpri stream Generic Function 

Outputs a newline to stream, and returns nil. It is identical in effect to: 

(write-char #\Newline stream) 

In CLIM, terpri is implemented by calling clim-lisp:stream-terpri. 

clim:stream-text-cursor stream Generic Function 

Returns the text cursor for the stream stream. 
The text cursor is of type climrcursor. 

clim:stream-text-margin stream Generic Function 

The X coordinate at which text wraps around (see clim:stream-end-of-line-action). 
The default setting is the width of the viewport, which is the right-hand edge of 
the viewport when it is horizontally scrolled to the "initial position". 

You can use setf on clim:stream-text-margin. If a value of nil is specified, the 
width of the viewport will be used. If the width of the viewport is later changed, 
the text-margin will change too. 

clim-lisp: stream-unread-char stream character Generic Function 

Places the specified character back into stream's, input buffer. The next read-char 
request will return the unread character. The character supplied must be the most 
recent character read from the stream. 

In CLIM, unread-char is implemented by calling clim-lisp:stream-unread-char. 

climrstream-unread-gesture stream gesture Generic Function 

Places the specified gesture back into stream's, input buffer. The next climrstream- 
read-gesture request will return the unread gesture. The gesture supplied must be 
the most recent gesture read from the stream. 

climrread-gesture is implemented by calling clim:stream-read-gesture. This func- 
tion is a generalization of clim-lisp: stream-unread-char to extended input 
streams. 

climrstream-vertical-spacing stream Generic Function 
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Returns the current inter-line spacing for the stream stream. 

clim-lisp: stream- write-char stream char Generic Function 

Writes char to stream and returns char as its value. 

In CLIM, write-char is implemented by calling clim-lisp:stream-write-char. 

clim-lisp:stream-write-string stream string &optional start end Generic Function 

Writes the string string to stream. If start and end are supplied, they specify what 
part of string to output, string is returned as the value. 

In CLIM, write-string is implemented by calling clim-lisp:stream-write-string. 

string &optional length Clim Presentation Type 

The presentation type that represents a string. If length is specified, the string 
must have exactly that many characters. 

climrsubset &rest elements Clim Presentation Type Abbreviation 

The presentation type that specifies a subset of elements. Values of this type are 
lists of zero or more values chosen from the possibilities in elements. The printed 
representation is the names of the elements separated by the separator character. 
The options (:name-key, rvalue-key, rpartial-completers, rseparator, and recho- 
space) are the same as for climrsubset-completion. 

climrsubset-completion sequence &key :test :value-key Clim Presentation Type 

The presentation type that selects one or more from a finite set of possibilities, 
with completion of partial inputs. The parameters and options are the same as for 
climrcompletion with the following additional options: 

rseparator The character that separates members of the set of possibili- 
ties in the printed representation when there is more than one. 
The default is comma. 

recho-space (t or nil) Whether to insert a space automatically after the 
separator. The default is t. 

The other subset types (climrsubset, climrsubset-sequence, and climrsubset-alist) 
are implemented in terms of the climrsubset-completion type. 

climrsubset-sequence sequence &key :test Clim Presentation Type Abbreviation 

Like climrsubset, except that the set of possibilities is the sequence sequence. The 
parameter :test and the options (mame-key, rvalue-key, rpartial-completers, 
rseparator, and recho-space) are the same as for climrsubset-completion. 
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clim:subset-alist alist &key :test Clim Presentation Type Abbreviation 

Like climrsubset, except that the set of possibilities is the alist alist. The parame- 
ter :test and the options (:name-key, rvalue-key, rpartial-completers, rseparator, 
and recho-space) are the same as for climrsubset-completion. The parameter alist 
has the same format as climrmember-alist. 



climrsubstitute-numeric-argument-marker command numeric-arg Function 

Given a command object command, this substitutes the value of numeric-arg for all 
occurrences of the value of clim:*numeric-argument-marker* in the command, 
and returns a command object with those substitutions. 



climrsuggest name &rest objects Function 

Specifies one possibility for clim:completing-from-suggestions. completion is a 
string, the printed representation, object is the internal representation. 

This function has lexical scope and is defined only inside the body of 
clim:completing-from-suggestions. 



clim:+super-key+ Constant 

The modifier state bit that corresponds to the user holding down the super key on 
the keyboard. See the section "Operators for Gestures in CLIM". 



clim:surrounding-output-with-border f&optional stream &key (.shape rrectanglej 

(■.move-cursor t)) &body body Macro 

Binds the local environment in such a way that the output of body will be sur- 
rounded by a border of the specified .shape. 

.shape The shape of the border to draw. The default is rrectangle. 

Other valid shapes are :oval, :drop-shadow, and runderline. 



■.move-cursor 



When t (the default), CLIM moves the text cursor to the end 
(lower right corner) of the output. Otherwise, the cursor is left 
at the beginning (upper left corner) of the output. 



symbol Clim Presentation Type 

The presentation type that represents a symbol. 

t Clim Presentation Type 

The supertype of all other presentation types. 
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Note that the climraccept method for this type allows input only via the pointer; 
if the user types anything on the keyboard, the climraccept method just beeps. 



clim:table-pane Class 

The layout pane class that arranges its children in a tabular format, climrtabling 
generates a pane of this type. 



climrtabling f&rest options) &body contents Macro 

The climrtabling macro lays out its child panes in a two-dimensional table ar- 
rangement. Each of the table is specified by an extra level of list in contents. For 
example, 



(cl im: tabl ing () 








(list 








(cl im: make-pane 


'label 


text 


"Red") 


(cl im:make-pane 


'label 


text 


"Green") 


(cl im:make-pane 


'label 


text 


"Blue")) 


(list 








(cl im:make-pane 


'label 


text 


" Intensity") 


(cl im:make-pane 


'label 


text 


"Hue") 


(cl im:make-pane 


'label 


text 


"Saturation"))) 



The climrtabling macro serves as the usual interface for creating a climrtable- 
pane. 



climrtest-presentation-translator translator presentation context-type frame window 
x y &key -.event (-.modifier-state 0) :for-menu Function 

Returns t if the translator translator applies to the presentation presentation in in- 
put context type context-type. (There is no from-type argument because it is derived 
from presentation.) 

frame is the application frame, window, x, and y are the window the presentation 
is on, and the X and Y position of the pointer (respectively). 

.-event and .-modifier-state are, respectively, a pointer button event and a modifier 
state. These are compared against the translator's gesture-name, .-event defaults to 
nil, and .-modifier-state defaults to 0, meaning that no shift keys are held down. 
Only one of .-event or .-modifier-state may be supplied. 

If :for-menu is t, the comparison against .-event and .-modifier-state is not done. 

presentation, context-type, frame, window, x, y, and .-event are passed along to the 
translator's tester if and when the tester is called. 

If the translator is not applicable, climrtest-presentation-translator will return 
nil. 
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climrtest-presentation-translator is responsible for matching type parameters and 
calling the translator's tester. Under some circumstances, climrtest-presentation- 
translator may also call the body of the translator to ensure that its value match- 
es to-type. 



climrtext-editor Class 

The climrtext-editor gadget class corresponds to a multi-line field containing text, 
a subclass of climrtext-field. 

The value of a text editor is the text string. 

See the section "Using Gadgets in CLIM". 

In addition to the usual pane initargs (rforeground, rbackground, rtext-style, 

space requirement options, and so forth), the following initargs are supported: 

:editable-p 

When nil, the text field cannot be modified. When t (the default), 
the text field can be modified. 

rncolumns 

An integer specifying the width of the text editor in characters. 

rnlines An integer specifying the height of the text editor in lines. 

(cl im: make-pane 'cl im: text-editor 
:value "Isn't Lisp the greatest?" 
: val ue-changed-cal 1 back ' text-f i el d-changed 
:ncolumns 40 :nlines 5) 

(defun text-field-changed (tf value) 

(format t "~&Text field ~A changed to ~S" tf value)) 



clim:text-editor-view Class 

The class that represents the view corresponding to a text editor pane (that is, a 
multi-line text editing field). 



clim:+text-editor-view+ Constant 

An instance of the class clim:text-editor-view. 

climrtext-field Class 

The gadget class that implements a text field. This is a subclass of both 
climrvalue-gadget and climraction-gadget. 

The value of a text field is the text string. 
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See the section "Using Gadgets in CLIM". 

In addition to the usual pane initargs (rforeground, rbackground, :text-style, 

space requirement options, and so forth), the following initargs are supported: 

:editable-p 

When nil, the text field cannot be modified. When t (the default), 
the text field can be modified. 

You might create a text field as follows: 

(cl im: make-pane 'cl im: text-field 
:value "Name of your product here" 
: val ue-changed-cal 1 back ' text-f i el d-changed 
:width 400) 

(defun text-field-changed (tf value) 

(format t "~&Text field ~A changed to ~S" tf value)) 



clim:text-field-view Class 

The class that represents the view corresponding to a text editor pane (that is, a 
single line text editing field). 



clim:+text-field-view+ Constant 

An instance of the class clim:text-field-view. 

clim:text-size medium string &key :text-style .start send Generic Function 

Computes how the cursor position would move if the specified string or character 
were output to medium starting at cursor position (0,0). clim:text-size does not 
take into account the value of clim:stream-text-margin when computing the size 
of the output. 

clim:text-size returns five values; 

• The total width of the string in device units; 

• The total height of the string in device units; 

• The final X cursor position, which is the same as the width if there are no 
#\Newline characters in the string; 

• The final Y cursor position, which is if the string has no ttsNewline char- 
acters in it, and is incremented by the line height for each ttsNewline char- 
acter in the string 

• The string's baseline. 

■.text-style defaults to (cl im: medium-text-style medium). 
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You can use .start and send to specify a substring of string. 

Note that clim:text-size is a low level function. Unless you are writing your own 
"formatting engine", if you find you need to use it very often, you may be working 
at too low a level of abstraction. 



clim:text-style Class 

The class that represents text styles. CLIM text styles have family, face, and size 
components. Each of these components has a corresponding reader accessor that 
can be used to extract a particular component from a text style. 

See the section "Text Styles in CLIM". 



clim:text-style-ascent text-style medium Generic Function 

The ascent (a real number) of text-style as it would be rendered on medium. 

The ascent of a text style is the ascent of the medium's font corresponding to text- 
style. The ascent of a font is the distance between the top of the tallest character 
in that font and the baseline. 

clim:text-style-components text-style medium Generic Function 

Returns the components of text-style as three values (family, face, and size). 

clim:text-style-descent text-style medium Generic Function 

The descent (a real number) of text-style as it would be rendered on medium. 

The descent of a text style is the descent of the medium's font corresponding to 
text-style. The descent of a font is the distance between the baseline and the bot- 
tom of the lowest descending character (usually "y", "q", "p", or "g"). 

clim:text-style-face text-style Generic Function 

Returns the face component of the text-style. 

clim:text-style-family text-style Generic Function 

Returns the family component of the text-style. 

clim:text-style-fixed-width-p text-style medium Generic Function 

Returns t if text-style will map to a fixed-width font on medium, otherwise returns 
nil. 
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clim:text-style-height text-style medium Generic Function 

Returns the height (a real number) of the "usual character" in text-style on medi- 
um. 

The height of a text style is the sum of its ascent and descent. 



clim:text-style-mapping port style &optional character-set Generic Function 

Returns the font object that will be used if characters in character-set in the text 
style style are drawn on any medium on the port port, character-set defaults to the 
standard character set. 

If the port is using exact text style mapping, CLIM will choose a font whose size 
exactly matches the size specified in the text style. Otherwise if the port is using 
loose text style mappings, CLIM will choose the font whose size is closest to the 
desired size. 

If no mapping exists, CLIM will signal an error. 



clim:text-style-mapping-exists-p port style &optional character-set exact-size-required 

Generic Function 

Returns t if there is a font associated with the text style style on the port port, 
otherwise returns nil. character-set defaults to the standard character set. If exact- 
size-required is t, only fonts whose size is the exact size specified in the text style 
will be considered to match. 



clim:text-style-p object Generic Function 

Returns t if and only if object is a CLIM text style, otherwise returns nil. 

clim:text-style-size text-style Generic Function 

Returns the size component of the text-style. 

clim:text-style-width text-style medium Generic Function 

Returns the width (a real number) of the "usual character" in text-style on medi- 
um. 

clim:textual-dialog-view Class 

The class that represents the view that is used inside textual climraccepting- 
values dialogs. 

clim:+textual-dialog-view+ Constant 
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An instance of the class clim:textual-dialog-view. Inside climraccepting-values, 
the default view for the dialog stream may be bound to 
clim:+textual-dialog-view+. 



clim:textual-menu-view Class 

The class that represents the view that is used inside textual menus. 

clim:+textual-menu-view+ Constant 

An instance of the class clim:textual-menu-view. Inside climrmenu-choose, the de- 
fault view for the menu stream may be bound to clim:+textual-menu-view+. 

clim:textual-view Class 

The class that represents textual views. Textual views are used in most command- 
line oriented applications. 

clim:+textual-view+ Constant 

An instance of the class clim:textual-view. 



climrthrow-highlighted-presentation presentation input-context button-press-event 

Function 

Calls the applicable translator for the presentation, input-context, and button-press- 
event (that is, the one corresponding to the user clicking a pointer button while 
over the presentation). This function returns an object and a presentation type. 
These values are returned from the translator to the call to climrwith-input- 
context that establish the matching input context. 

When you call climrthrow-highlighted-presentation yourself, you should be careful 
to ensure that clim:*application-frame* is bound to the relevant application frame 



clim:title-pane Class 

The pane class that is used to implement a title pane. It corresponds to the pane 
type abbreviation rtitle in the rpanes clause of clim:define-application-frame. The 
default display function for panes of this type is clim:display-title. 

For clim:title-pane, the default for the :display-time option is t, and the default 
for the :scroll-bars option is nil. 



climrtoggle-button Class 

The climrtoggle-button gadget class provides "on/off" switch behavior. It is a sub- 
class of climrvalue-gadget and climrlabelled-gadget-mixin. This gadget typically 
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appears as a box that is optionally highlighted with a check-mark. If the check- 
mark is present, the gadget's value is t, otherwise it is nil. 

See the section "Using Gadgets in CLIM". 

In addition to the initargs for climrvalue-gadget and the usual pane initargs 
(rforeground, rbackground, :text-style, space requirement options, and so forth), 
the following initargs are supported: 

rlabel A string or pixmap that is used to label the button. 

:indicator-type 

This is used to initialize the indicator type property for the gadget, 
and must be either :one-of or :some-of. The indicator type controls 
the appearance of the toggle button. For example, many toolkits 
present a one-of-many choice differently from a some-of-many 
choice. 

climrarmed-callback will be invoked when the toggle button becomes armed (such 
as when the pointer moves into it, or a pointer button is pressed over it). When 
the toggle button is actually activated (by releasing the pointer button over it), 
climrvalue-changed-callback will be invoked. Finally, climrdisarmed-callback will 
be invoked after climrvalue-changed-callback, or when the pointer is moved out- 
side of the toggle button. 

Calling climrgadget-value on a toggle button will return t if the button is select- 
ed, otherwise it will return nil. The value of the toggle button can be changed by 
calling setf on climrgadget-value. 

A toggle button might be created as follows: 

(cl im: make-pane 'cl im: toggle-button 
:label "Toggle" :width 80 
: val ue-changed-cal 1 back ' toggl e-button-cal 1 back) 

(defun toggle-button-callback (button value) 

(format t "~&Button ~A toggled to ~S" (cl im: gadget-label button) value)) 



climrtoggle-button-view Class 

The class that represents the view corresponding to a toggle button. This is usual- 
ly used for boolean (yes or no) values. 



climr+toggle-button-view+ Constant 

An instance of the class climrtoggle-button-view. 

climrtoken-or-type tokens type Clim Presentation Type Abbreviation 



Page 1666 



A compound type that is used to select one of a set of special tokens, or an object 
of type type, tokens is anything that can be used as the alist parameter to 
clim:member-alist; typically it is a list of keyword symbols. 

type can be a presentation type abbreviation. 

For example, the following is a common way of using clim:token-or-type: 

(cl im:accept ' (cl im: token-or-type (:all :none) integer) 
: prompt "How many?") 



climrtracking-pointer f&optional stream &key .-pointer .-multiple-window itransformp 
(-.context-type t) .-highlight) &body clauses Macro 

Provides a general means for running code while following the position of a point- 
ing device on the stream stream, and monitoring for other input events, stream de- 
faults to *standard-input*. 

Programmer-supplied code may be run upon occurrence of any of the following 
types of events: 

• Motion of the pointer 

• Motion of the pointer over a presentation 

• Clicking or releasing a pointer button 

• Clicking or releasing a pointer button over a presentation 

• Keyboard event (typing a character) 

The keyword arguments to climrtracking-pointer are: 

.-pointer Specifies a pointer to track. It defaults to (climrport-pointer 
(climrport stream)). Unless there is more than one pointing device 
available, it is unlikely that this option will be useful. 

.-multiple-window 

When t, specifies that the pointer is to be tracked across multiple 
windows. The default is nil. 

Note that when .-multiple-window is t, the climrtracking-pointer 
clauses will be invoked on many different types of panes besides 
just CLIM stream panes, including scroll bars, borders, and so 
forth. Your program must filter out any panes it is not interested 
in. 

itransformp 

When t, specifies that coordinates supplied to the -.pointer-motion 
clause are to be expressed in the user coordinate system. The de- 
fault is nil. 

-.context-type 

Specifies the type of presentations that will be "visible" to the 
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tracking code. It defaults to t, meaning that all presentations are 
visible. 

.■highlight Specifies whether or not CLIM should highlight presentations. It de- 
faults to t when there are any presentation clauses, meaning that 
presentations that match xontext-type should be highlighted. If there 
are no presentation clauses, it defaults to nil. 

The body of climrtracking-pointer consists of clauses. Each clause in clauses is of 
the form {clause-keyword arglist &body clause-body) and defines a local function to 
be run upon occurrence of each type of event. The possible clause-keywords, their 
arglists, and their uses are: 

rpointer-motion {window x y) 

Defines a clause that runs whenever the pointer moves. In the 
clause, window is bound to the window in which the motion oc- 
curred, and x and y to the coordinates of the pointer. (See the key- 
word argument rtransformp above for a description of the coordi- 
nate system in which x and y is expressed.) 

When both rpresentation and rpointer-motion clauses are provided, 
only one of them will be run for a given motion event. The rpresen- 
tation clause will run if it is applicable, otherwise the rpointer- 
motion clause will run. 

rpointer-button-press {event x y) 

Defines a clause that runs whenever a pointer button is pressed. In 
the clause, event is bound to the event object. (The window and the 
coordinates of the pointer are part of event.) 

When both rpresentation-button-press and rpointer-button-press 

clauses are provided, only one of them will be run for a given but- 
ton press event. The rpresentation-button-press clause will run if 
it is applicable, otherwise the rpointer-button-press clause will run. 

x and y are the transformed X and Y positions of the pointer. These 
will be different from climrpointer-event-x and climrpointer- 
event-y if stream is using a non-identity transformation. 

rpointer-button-release {event x y) 

Defines a clause that runs whenever the pointer button is released. 
In the clause, event is bound to the event object. (The window and 
the coordinates of the pointer are part of event.) 

When both rpresentation-button-release and rpointer-button- 
release clauses are provided, only one of them will be run for a 
given button release event. The rpresentation-button-release clause 
will run if it is applicable, otherwise the rpointer-button-release 
clause will run. 

x and y are the transformed X and Y positions of the pointer. These 
will be different from climrpointer-event-x and climrpointer- 
event-y if stream is using a non-identity transformation. 
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rpresentation (presentation window x y) 

Defines a clause that runs whenever the pointer moves over a pre- 
sentation of the desired type. (See the keyword argument rcontext- 
type above for a description of how to specify the desired type.) In 
the clause, presentation is bound to the presentation, window to the 
window in which the motion occurred, and x and y to the coordi- 
nates of the pointer. (See the keyword argument rtransformp above 
for a description of the coordinate system in which x and y is ex- 
pressed.) 

:presentation-button-press (presentation event x y) 

Defines a clause that runs whenever the pointer button is pressed 
while the pointer is over a presentation of the desired type. (See the 
keyword argument :context-type above for a description of how to 
specify the desired type.) In the clause, presentation is bound to the 
presentation, and event to the event object. (The window and the co- 
ordinates of the pointer are part of event.) 

x and y are the transformed X and Y positions of the pointer. These 
will be different from clim:pointer-event-x and climrpointer- 
event-y if stream is using a non-identity transformation. 

rpresentation-button-release (presentation event x y) 

Defines a clause that runs whenever the pointer button is released 
while the pointer is over a presentation of the desired type. (See the 
keyword argument :context-type above for a description of how to 
specify the desired type.) In the clause, presentation is bound to the 
presentation, and event to the event object. (The window and the co- 
ordinates of the pointer are part of event.) 

x and y are the transformed X and Y positions of the pointer. These 
will be different from clim:pointer-event-x and climrpointer- 
event-y if stream is using a non-identity transformation. 

rkeyboard (event) 

Defines a clause that runs whenever a key is typed on the keyboard. 
In the clause, event is bound to the keyboard event typed. If the 
event corresponds to a standard printing character, event may be a 
character object. 

A simple version of clim:pointer-place-rubber-band-line* could be implemented in 
the following manner using climrtracking-pointer. 
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(defun pointer-place-rubber-band-1 inex (&optional (stream xstandard-inputx)) 
(let (start-x start-y end-x end-y) 

(flet ((finish (event finish &optional press) 

(let ((x (cl im:pointer-event-x event)) 
(y (cl im:pointer-event-y event)) 
(window (cl im: event-sheet event))) 
(when (eq window stream) 
(cond (start-x 

(cl im:with-output- recording-opt ions 
(window :draw t : record nil) 
(cl im:draw-l inex window start-x start-y end-x end-y 
:ink cl im:+fl ipping-ink+)) 
(cl im:draw-l inex window start-x start-y end-x end-y) 
(when finish 

(return- from pointer-place-rubber-band-1 inex 
(values start-x start-y end-x end-y)))) 
(press (setq start-x x start-y y))))))) 
(declare (dynamic-extent tf'finish)) 
(cl im: tracking-pointer (stream) 
( :pointer-motion (window x y) 
(when (and start-x (eq window stream)) 

(cl im:with-output-recording-options (window :draw t : record nil) 
(when end-x 

(cl im:draw-l inex window start-x start-y end-x end-y 
:ink cl im:+fl ipping-ink+)) 
(setq end-x x end-y y) 

(cl im:draw-l inex window start-x start-y end-x end-y 
:ink cl im:+fl ipping-ink+)))) 
( :pointer-button-press (event) 

(finish event nil t)) 
( :pointer-button-release (event) 
(finish event t)))))) 



climrtransform-distance transform dx dy Generic Function 

Applies transform to the distance represented by dx and dy, and returns two val- 
ues, the transformed dx and the transformed dy. 

A distance represents the difference between two points. It does not transform like 
a point. 



climrtransform-position transform x y Generic Function 

Applies transform to the point whose coordinates are x and y, and returns two val- 
ues, the transformed X-coordinate and the transformed Y-coordinate. 

climrtransform-position is the spread version of climrtransform-region in the 
case where the region is a point. 
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climrtransform-rectangle* transform xl yl x2 y2 Generic Function 

Applies the transformation transform to the rectangle specified by the four coordi- 
nate arguments, which are real numbers. One corner of the rectangle is at (xl,yl) 
and the opposite corner is at (x2,y2). If transform is not a rectilinear transforma- 
tion, this will signal an error. 

This returns four values that specify the minimum and maximum points of the 
transformed rectangle in the order min-x, min-y, max-x, and max-y. 

climrtransform-rectangle* is the spread version of climrtransform-region in the 
case where the transformation is rectilinear and the region is a rectangle. 



climrtransform-region transformation region Generic Function 

Applies transformation to region, and returns a new transformed region. 

Transforming a region applies a coordinate transformation to that region, thus 
moving its position on the drawing plane, rotating it, or scaling it. Note that this 
creates a new region, it does not side-effect the region argument. 

climrtransformation Class 

The protocol class for all transformations. There are one or more subclasses of 
climrtransformation with implementation-dependent names that implement trans- 
formations. If you want to create a new class that obeys the transformation proto- 
col, it must be a subclass of climrtransformation. 

climrtransformation-equal transforml transform2 Generic Function 

Returns t if the two transformations have equivalent effects (that is, are mathe- 
matically equal), otherwise returns nil. 

climrtransformation-underspecified Condition 

The condition that is signalled when you try to make a 3-point transformation 
from three collinear points. 

climrtransformationp object Function 

Returns t if an only if object is a CLIM transformation. 

climrtranslate-coordinates x-delta y-delta &body coordinate-pairs Function 

Translates each of the X and Y coordinate pairs in coordinate-pairs by x-delta and 
y-delta. x-delta and y-delta are real numbers. 
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clim:translation-transformation-p transform Generic Function 

Returns t if transform is a pure translation, that is a transformation that moves 
every point by the same distance in X and the same distance in Y, otherwise re- 
turns nil. 



clim:+transparent-ink+ Constant 

When you draw a design that has areas of clim:+transparent-ink+, the former 
background shows through in those areas. Typically, clim:+transparent-ink+ is 
used as one of the inks in a pattern so that parts of the pattern are transparent. 



climrtree-recompute-extent record Generic Function 

You can use this function to ensure that the bounding rectangles for a tree of out- 
put records are up to date. Use this whenever the bounding rectangles of a num- 
ber of children of a record have been changed, such as happens during table and 
graph formatting, climrtree-recompute-extent computes the bounding rectangle 
large enough to contain all of the children of record, adjusts the bounding rectan- 
gle of record accordingly, and then calls clim:recompute-extent-for-changed-child 
on record. 

If you write a new formatting facility that rearranges many of the descendants of 
an output record (for example, a new kind of graph formatting), you should call 
climrtree-recompute-extent on the parent of the highest level record that was af- 
fected. It is preferable to use climrtree-recompute-extent instead of repeatedly 
calling climrrecompute-extent-for-changed-child, because you will get better per- 
formance. 

See the section "Concepts of CLIM Output Recording". 



climrtype-or-string type Clim Presentation Type Abbreviation 

A compound type that is used to select an object of type type or an arbitrary 
string, for example, (climrtype-or-string integer). Any input that climraccept can- 
not parse as the representation of an object of type type is returned as a string. 

type can be a presentation type abbreviation. 



climrunhighlight-highlighted-presentation stream &optional (prefer-pointer-window 
t) Function 

Unhighlights any highlighted presentations on stream. 

If prefer-pointer-window is t (the default), this clears the highlighted presentation 
for the window that is located under the pointer. Otherwise it clears the highlight- 
ed presentation for the window stream. 



climrunread-gesture gesture &key (.stream *standard-input*) Function 
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Places the specified gesture back into .stream's input buffer. The next climrread- 
gesture request will return the unread gesture. The gesture supplied must be the 
most recent gesture read from the stream. 



climr*unsupplied-argument-marker* Variable 

If you are building a command object that has required arguments that have not 
yet been supplied, use the value of climr*unsupplied-argument-marker* as a 
placeholder for those arguments. When CLIM goes to execute a command that has 
any unsupplied arguments, it will first gather those arguments from the user via a 
menu or a dialog. 

For example, if you have a Hardcopy File command that takes two required argu- 
ments, a pathname and a printer, you might write a translator as follows: 

(cl im:def ine-presen tat ion-to-command- translator printer-to-hardcopy-f ile 
(printer com-hardcopy-f ile hardcopy 
: gesture : select 

:pointer-documentation "Hardcopy File") 
(object) 
(list cl im:*unsuppl ied-argumentx object)) 



climruntransform-distance transform dx dy Generic Function 

Applies the inverse of transform to the distance represented by dx and dy, and re- 
turns two values, the transformed dx and the transformed dy. 

A distance represents the difference between two points. It does not transform like 
a point. 



climruntransform-position transform x y Generic Function 

Applies the inverse of transform to the point whose coordinates are x and y, and 
returns two values, the transformed X-coordinate and the transformed Y-coordi- 
nate. 

climruntransform-position is the spread version of climruntransform-region in 

the case where the region is a point. 



climruntransform-rectangle* transform xl yl x2 y2 Generic Function 

Applies the inverse of transform to the rectangle specified by the four coordinate 
arguments, and returns four values that specify the minimum and maximum points 
of the transformed rectangle. 

climruntransform-rectangle* is the spread version of climruntransform-region in 

the case where the region is a rectangle. 
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climruntransform-region transformation region Generic Function 

Applies the inverse of transformation to region and returns a new transformed re- 
gion. 

This is equivalent to: 

(cl im: transform- region 

(cl im: invert-transformation transform) region) 



climrupdating-output (stream &rest args &key (:record-type "climrstandard- 
updating-output-record) :unique-id (:id-test '#'eql) xache-value (:cache-test '#'eql) 
xopy-cache-value .-parent-cache : output-record .-fixed-position :all-new &allow-other- 
keys) &body body 

Macro 

Informs CLIM's incremental redisplay facilities of the characteristics of the output 
done by body to stream. Within climrupdating-output, you name a piece of output 
(with a unique id), and you state how to determine whether the output changes 
(with a cache value). 

For related information, see the section "Using climrupdating-output". 

:unique-id~Provi&es a means to uniquely identify this output. If -.unique-id is 
not supplied, CLIM will generate one that is guaranteed to be 
unique. 

:id-test A function of two arguments that is used for comparing unique ids. 
It defaults to eql. 

-.cache-value 

A value that remains constant if and only if the output produced by 
body does not need to be recomputed. If the cache value is not sup- 
plied, CLIM will not use a cache for this piece of output. 

-.cache-test A function of two arguments that is used for comparing cache val- 
ues. It defaults to eql. 

xopy-cache-value 

Controls whether the specified cache value should be copied using 
copy-seq before it is stored in the output record. 

.-fixed-position 

Declares that the location of this output is fixed relative to its su- 
perior. When CLIM redisplays an output record which specified 
rfixed-position t, if the contents have not changed, the position of 
the output record will not change. If the contents have changed, 
CLIM assumes that the code will take care to preserve its position. 

:all-new Indicates that all of the output done by body is new, and will never 
match output previously recorded. 
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■.record-type 

The type of output record that should be constructed. This defaults 
to CLIM's standard climrupdating-output-record class. 



clim:user-command-table Clim Command Table 

A command table reserved for user-defined commands. 

clim-sys:using-resource (variable resource &rest parameters) &body body Macro 

The forms in body are evaluated with variable bound to an object allocated from 
the resource named name, using the parameters given by parameters. The parame- 
ters (if any) are evaluated, but name is not. 

After the body has been evaluated, clim-sys:using-resource returns the object in 
variable back to the resource. If some form in the body sets variable to nil, the ob- 
ject will not be returned to the resource. Otherwise, the body should not changes 
the value of variable. 

See the section "Resources in CLIM". 

climrvalue-changed-callback gadget client id value Generic Function 

This callback is invoked when the value of a gadget is changed, either by the user 
or programatically. 

The default method (on climrvalue-gadget) calls the function specified by the 
rvalue-changed-callback initarg with two arguments, the gadget and the new val- 
ue. 

Although you can specialize this function yourself, generally this function will sim- 
ply call another programmer-specified callback function. 

See the section "Using Gadgets in CLIM". 

climrvalue-gadget Class 

The class used by gadgets that have a value; a subclass of climrbasic-gadget. 

All subclasses of climrvalue-gadget must handle the two initargs rvalue and 
rvalue-changed-callback, which are used to specify, respectively, the initial value 
and the value changed callback of the gadget. The value changed callback is either 
nil or a function of two arguments, the gadget and the new value. 



climrvertically f&rest options &key .spacing &allow-other-keys) &body contents 

Macro 

The climrvertically macro lays out one or more child panes vertically, from top to 
bottom. The climrvertically macro serves as the usual interface for creating a 
climrvbox-pane. 
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.spacing is an integer that specifies how much space should be left between each 
child pane, in device units, options may include other pane initargs, such as space 
requirement options, rforeground, rbackground, :text-style, and so forth. 

contents is one or more forms that produce the child panes. Each form in contents 
is of the form: 

• A pane. The pane is inserted at this point and its space requirements are used 
to compute the size. 

• A number. The specified number of device units should be allocated at this 
point. 

• The symbol clim:+fill+. This means that an arbitrary amount of space can be 
absorbed at this point in the layout. 

• A list whose first element is a number and whose second element evaluates to a 
pane. If the number is less than 1, then it means that that percentage of excess 
space or deficit should be allocated to the pane. If the number is greater than 
or equal to 1, then that many device units are allocated to the pane. For exam- 
ple: 

(cl im: vertical ly () 

(9/10 (cl im:make-cl im-appl i cation-pane)) 
(1/10 (cl im:make-cl im-interac tor-pane))) 

would create a vertical stack of two stream panes. The application pane takes 
nine-tenths of the space, and the interactor pane takes one-tenth of the space. 

See the section "Using the :LAYOUTS Option to CLIM:DEFINE-APPLICATION- 
FRAME". 



clim:vbox-pane Class 

The layout pane class that arranges its children in a vertical stack, climrvertically 
generates a pane of this type. 

In addition to the usual sheet initargs (the space requirement initargs, 
rforeground, rbackground, and rtext-style), this class supports two other initargs: 

rspacing An integer that specifies the amount of space to leave between each 
of the child panes, in device units. 

rcontents A list of panes that will be the child panes of the box pane. 



climrwindow-children window Generic Function 

Returns a list of all of the windows that are children (inferiors) of window. 
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This is identical to climrsheet-children, and is included only for compatibility with 
CLIM 1.1. 



clim:window-clear window Generic Function 

Clears the entire drawing plane of window, filling it with the background design. 
clim:window-clear also discards the window's output history and resets the cursor 
position to the upper left corner. 



clim:window-erase-viewport window Generic Function 

Clears the visible part of the drawing plane of window, filling it with the back- 
ground design. 



clim:window-event Class 

The class that corresponds to any sort of window event. 

clim:window-event-region window-event Generic Function 

Returns the region that was affected by the window event window-event. 

climrwindow-expose window Generic Function 

Makes the window visible on the screen. 

This is identical to (setf (climrwindow-visibility window) t), and is included only 
for compatibility with CLIM 1.1. 

climrwindow-inside-bottom window Function 

Returns the coordinate of the bottom edge of the window window. 

clim:window-inside-edges window Generic Function 

Returns four values, the coordinates of the left, top, right, and bottom inside edges 
of the window window. The inside edges are computed by subtracted the window's 
margins from the window's outside edges. (The outside edges of a window can be 
obtained by calling climrbounding-rectangle* on the window.) 

climrwindow-inside-height window Function 

Returns the inside height of window. 

clim:window-inside-left window Function 
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Returns the coordinate of the left edge of the window window. 

clim:window-inside-right window Function 

Returns the coordinate of the right edge of the window window. 

clim:window-inside-size window Generic Function 

Returns the inside width and height of window as two values. 

clim:window-inside-top window Function 

Returns the coordinate of the top edge of the window window. 

clim:window-inside-width window Function 

Returns the inside width of window. 

clim:window-label window Generic Function 

Returns the label (a string) associated with window, or nil if there is none. You 
can use setf of clim:window-label to give window a new label. 

climrwindow-parent window Generic Function 

Returns the window that is the parent (superior) of window. 

This is identical to climrsheet-parent, and is included only for compatibility with 
CLIM 1.1. 

climrwindow-refresh window Generic Function 

Clears the visible part of the drawing plane of window, and then replays all of the 
output records in the visible part of the drawing plane. 

clim:window-set-viewport-position window x y Generic Function 

Moves the top-left corner of the window's viewport. This is how you scroll a win- 
dow. This function is provided as a more convenient interface to climrscroll-extent 
for the benefit of CLIM 1.1 programs. 

clim:window-set-viewport-position, and all other functions that change the posi- 
tion of the viewport, also call climrnote-viewport-position-changed to notify the 
window that it has been scrolled. 

clim:window-stack-on-bottom window Generic Function 
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Puts the window underneath all other windows that it overlaps. 



clim:window-stack-on-top window Generic Function 

Puts the window on top of all other windows that it overlaps, so you can see all of 
it. 



climrwindow-viewport window Generic Function 

If the pane window is part of a scroller pane, this returns the region of window's 
viewport. Otherwise it returns the region of window itself. 

It is often more convenient to use this function instead of climrpane-viewport- 
region. 



climrwindow-viewport-position window Generic Function 

Returns two values, the X and Y coordinates of the top-left corner of the window's 
viewport. 

climrwindow-visibility stream Generic Function 

A predicate that returns true if the window is visible. You can use setf on 
climrwindow-visibility to expose or deexpose the window. 

Note that it is implementation-dependent whether this is true when the window is 
partially visible (or partially covered by an overlapping window). 

clim:with-accept-help options &body body Macro 

Binds the local environment to control Help and control-? documentation for input 
to climraccept. 

options is a list of option specifications. Each specification is itself a list of the 
form (help-option help-string), help-option is either a symbol that is a help-type or a 
list of the form (help-type mode- flag). 

help-type must be one of: 

:top-level-help 

Specifies that help-string be used instead of the default help docu- 
mentation provided by climraccept. 

rsubhelp Specifies that help-string be used in addition to the default help doc- 
umentation provided by climraccept. 

mode-flag must be one of: 

rappend Specifies that the current help string be appended to any previous 
help strings of the same help type. This is the default mode. 
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roverride Specifies that the current help string is the help for this help type; 
no lower-level calls to clim:with-accept-help can override this. 
(That is, roverride works from the outside in.) 

restablish-unless-overridden 

Specifies that the current help string be the help for this help type 
unless a higher-level call to clim:with-accept-help has already es- 
tablished a help string for this help type in the roverride mode. 
This is what climraccept uses to establish the default help. 

help-string is a string or a function that returns a string. If it is a function, it re- 
ceives three arguments, the stream, an action (either rhelp or rpossibilities) and 
the help string generated so far. 

None of the arguments is evaluated. 

See the section "Utilities for climraccept Presentation Methods". 



climrwith-activation-gestures (additional-gestures &key .-override) &body body 

Macro 

Specifies gestures that terminate input during the evaluation of body, additional- 
gestures is a gesture spec or a form that evaluates to a list of gesture specs. 

If .-override is t, then then additional-gestures will override the existing activation 
gestures. If it is nil (the default), then additional-gestures will be added to the ex- 
isting set of activation gestures. 

See the r activation-gestures option to climraccept. See also see the variable 
climr*standard-activation-gestures*. 



climrwith-application-frame (frame) &body body Macro 

Evaluates body with the variable frame bound to the current application frame. 

climrwith-delimiter-gestures (additional-gestures &key .-override) &body body Macro 

Specifies gestures that terminate an individual token but not the entire input sen- 
tence during the evaluation of body, additional-gestures is a gesture spec or a form 
that evaluates to a list of gesture specs. 

If .-override is t, then then additional-gestures will override the existing delimiter 
gestures. If it is nil (the default), then additional-gestures will be added to the ex- 
isting set of delimiter gestures. 

See the r delimiter-gestures option to climraccept . 

climrwith-bounding-rectangle* (left top right bottom) region &body body Macro 

Binds left, top, right, and bottom to the edges of the bounding rectangle of region, 
and then evaluates body in that context. 
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left X coordinate of the left side of the region. 

top Y coordinate of the top side of the region. 

right X coordinate of the right side of the region. 

bottom Y coordinate of the bottom side of the region. 

region A bounded region or a sheet that has a bounded region. For exam- 
ple, a window, and output record, or a geometric object such as a 
line or an ellipse. 



See the section "Bounding Rectangles in CLIM". 



clim:with-command-table-keystrokes (keystroke-var command-table) &body body 

Macro 

Binds keystroke-var to a list that contains all of the keystroke accelerators in the 
command table command-table, and then evaluates body in that context. 

(cl im:with-command-table-keystrokes (keystrokes command-table) 
(let ((command (cl im: read-command-using-keystrokes 
command-table keystrokes 
: stream command-stream))) 
(if (and command (not (typep command 'cl im: key-press-event))) 
(cl im: execute-frame-command frame command) 
(dim: beep stream)))) 

In general, the keystroke accelerators you choose should not be any characters that 
a user can normally type in during an interaction. So for an application using a 
command-line interface style, they will typically be non-printing characters such as 

ttScontrol -E. 

This macro generates keystrokes suitable for use by climrread-command-using- 
keystrokes. 



climrwith-drawing-options (medium &key sink .-clipping-region .-transformation 
.-line-style -.line-unit :line-thickness :line-dashes :line-joint-shape :line-cap-shape .-text- 
style .-text-family -.text-face :text-size) Macro 

Binds the state of medium to correspond to the supplied drawing options, and eval- 
uates the body with the new drawing options in effect. Each option causes binding 
of the corresponding component of the medium for the dynamic extent of the body. 

medium can be a medium, a sheet that supports output, or a stream. 

Any call to a drawing function can supply a drawing option to override the prevail- 
ing one. In other words, the drawing functions effectively do a climrwith-drawing- 
options when drawing option arguments are supplied to them. 

The default value specified for a drawing option is the value to which the corre- 
sponding component of a medium is normally initialized. 
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For information on the drawing options, see the section "Set of CLIM Drawing Op- 
tions". 

You can often realize performance improvements when doing graphical output by 
wrapping a single call to climrwith-drawing-options around calls to multiple draw- 
ing functions that use the same drawing options. See the macro climrwith- 
medium-state-cached. 



clim:with-end-of-line-action (stream action) &body body Macro 

Temporarily changes the end of line action for the duration of evaluation of body. 
The end of line action controls what happens if the cursor position moves horizon- 
tally out of the viewport, or if text output reaches the text margin. (By default the 
text margin is the width of the viewport, so these are usually the same thing.) 

The end of line action is one of: 

:wrap When doing text output, wrap the text around (that is, break 
the text line and start another line). When setting the cursor 
position, scroll the window horizontally to keep the cursor posi- 
tion inside the viewport. This is the default. 

rscroll Scroll the window horizontally to keep the cursor position in- 
side the viewport, then keep doing output. 

rallow Ignore the text margin and just keep doing output. 



clim:with-end-of-page-action (stream action) &body body Macro 

Temporarily changes the end of page action for the duration of evaluation of body. 
The end of page action controls what happens if the cursor moves vertically out of 
the viewport. 

The end of page action is one of: 

rscroll Scroll the window vertically to keep the cursor position inside 
the viewport, then keep doing output. This is the default. 

rallow Ignore the viewport and just keep doing output. 

rwrap Wrap the text around (that is, go back to the top of the view- 
port). This is not currently implemented. 



climrwith-first-quadrant-coordinates f&optional stream x y) &body body Macro 

Binds the dynamic environment to establish a local coordinate system with the pos- 
itive X-axis extending to the right and the positive Y-axis extending upward, with 
(0,0) at the current cursor position of stream. 



Page 1682 



clim:with-input-context (type &key .-override) f&optional object-var type-var event- 
var options-var) form &body clauses Macro 

Establishes an input context of type type. When .-override is nil (the default), this 
invocation of clim:with-input-context adds its context presentation type to the ex- 
tant context. In this way an application can solicit more than one type of input at 
the same time. When .-override is t, it overrides the current input context rather 
than nesting inside the current input context. 

After establishing the new input context, form is evaluated. If no pointer gestures 
are made by the end user during the evaluation of form, all of the values of form 
are returned. Otherwise, if the user invoked a translator by clicking on an object, 
one of the clauses is evaluated, based on the presentation type of the object re- 
turned by the translator. All of the values of that clause are are returned as the 
values of clim:with-input-context. During the evaluation of one of the clauses, ob- 
ject-var is bound to the object returned by the translator, type-var is bound to the 
presentation type returned by the translator, and event-var is bound to the event 
corresponding to the user's gesture, options-var is bound to any options that the 
translator might have returned, and will be either nil or a list of keyword-value 
pairs. 

clauses is constructed like a typecase statement clause list whose keys are presen- 
tation types. 

Note that, when one of the clauses is evaluated, nothing is inserted into the input 
buffer. If you want to insert input corresponding to the object the user clicked on, 
you must call clim:replace-input or clim:presentation-replace-input. 

Only the arguments type and .-override are evaluated. 

(cl im: with- input-context ('pathname) 

(path) 
(read) 
(pathname 

(format t "~&The pathname ~A was clicked on." path))) 



clim:with-input-editing f&optional stream &key dnput-sensitizer -.initial-contents 
-.class) &body body Macro 

Establishes a context in which the user can edit the input he or she types in on 
the stream stream, body is then evaluated in this context, and the values returned 
by body are returned as the values of clim:with-input-editing. stream defaults to 
*standard-input*. 

.-class defaults to CLIM's standard input editing stream class, dnput-sensitizer, if it 
is supplied, is a function of two arguments, a stream and a continuation. The dn- 
put-sensitizer function should call the continuation on the stream. For example, the 
implementation of climraccept uses something like the following in order to make 
the user's input sensitive as a presentation for later use: 
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(flet ((input-sensitizer (continuation stream) 
(if (cl im:stream-record-p stream) 

(cl im:with-output-as-presentation (stream object type) 

(funcall continuation stream)) 
(funcall continuation stream)))) 
(cl im:with-input-editing (stream : input-sensitizer #' input-sensitizer) 
...)) 

.■initial-contents is a string to use as the initial contents of the buffer for the 
stream to be edited. 

See the section "Input Editing and Built-in Keystroke Commands in CLIM". 



clim:with-input-editor-typeout f&optional stream &key .-erase) &body body Macro 

If, when you are inside of a call to clim:with-input-editing, you want to perform 
some sort of typeout, it should be done inside clim:with-input-editor-typeout. 
stream is the input editing stream and body is the code that will do output to the 
stream, stream defaults to *standard-input*. 

For more information on the input editor, see the section "The Structure of the 
CLIM Input Editor". 



clim:with-input-focus (stream) &body body Macro 

Temporarily gives the keyboard input focus to the given window (which is most 
often an interactor pane). By default, a frame will give the input focus to the 
clim:frame-query-io pane. 

For example, suppose you want the user to supply some input in a "pop up", after 
which the window "pops down" again. The following function will do this. 

(defun do-pop-up-text-editing (window) 
(setf (cl im:window-visibil ity window) t) 
(unwind-protect 

(cl im:with-input-focus (window) 
(cl im:with-input-editing (window) 

(cl imiwith-activation-gestures ('(:end) :override t) 
(unwind-protect 

(cl im: read-token window) 
;; Eat the activation gesture if it's still there 
(cl im: read-gesture :stream window :peek-p t :timeout 0))))) 
(setf (cl im:window-visibil ity window) nil))) 



clim:with-local-coordinates f&optional stream x y) &body body Macro 
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Binds the dynamic environment to establish a local coordinate system with the pos- 
itive X-axis extending to the right and the positive Y-axis extending downward, 
with (0,0) at the current cursor position of stream. 



clim-sys:with-lock-held (place &optional state) &body forms Macro 

Evaluates body while holding the lock named by place, place is a reference to a 
lock created by clim-sys:make-lock. 

On systems that do not support locking, clim-sys:with-lock-held is equivalent to 
progn. 

See the section "Locks in CLIM". 



clim:with-medium-state-cached (medium) &body body Macro 

Declares that all of the drawing operations within body will use exactly the same 
drawing options. This allows CLIM back-ends to cache the state of the medium so 
that the medium does not need to be "decoded" for each drawing operation. Used 
in conjunction with climrwith-drawing-options, this can result in substantial per- 
formance improvements when doing graphical output, whether or not output 
recording is enabled or disabled. 



clim:with-menu (menu &optional associated-window &rest options &key .-label 
.scroll-bars) &body body Macro 

Binds menu to a temporary window, exposes the window on the same screen as the 
associated-window, runs the body, and then deexposes the window. The values re- 
turned by clim:with-menu are the values returned by body. 

menu The name of a variable which is bound to the window to be used 
for the menu. 

associated-window 

A window that this window is associated with, typically a pane of an 
application frame. If not supplied, associated-window will default to 
the top-level window of the current application frame. 

■.label A string to use to label the menu. The default is nil, meaning that 
there is no label. 

.scroll-bars 

Indicates whether the new window should have scroll bars. One of 
nil, :none, rvertical, rhorizontal, or :both. The default is rvertical. 

Example 

This example shows how to use clim:with-menu with climrmenu-choose-from- 
drawer to draw a temporary menu. 
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(defun choose-compass-di recti on () 

(labels ((draw-compass-point (stream ptype symbol x y) 

(cl im:with-output-as-presentation (stream symbol ptype) 
(cl im:draw-stringx stream (symbol-name symbol) 

x y 

:align-x :center 
:align-y :center 
: text-style 

' ( : sans-serif : roman : large)))) 
(draw-compass (stream ptype) 

(cl im:draw-l ine* stream 25 -25 
: 1 ine-thickness 2) 
(cl im:draw-l ine* stream 25 -25 
: 1 ine-thickness 2) 
(loop for point in '((n -30) (s 30) 

(e 30 0) (w -30 0)) 
do (apply tf'draw-compass-point 
stream ptype point)))) 
(cl im:with-menu (menu) 

(cl im : menu-choose- from-d rawer 
menu 'cl im:menu-item tf'draw-compass)))) 

clim:with-menu can also be used to allocate a temporary window for other uses. 
You can use clim:position-sheet-carefully and clim:size-frame-from-contents to 

set the size and position of windows created using clim:with-menu. 



clim:with-new-output-record (stream &optional record-type record &rest initargs) 
&body body Macro 

Creates a new output record of type record-type (which defaults to CLIM's default 
"linear" output record) and then captures the output of body into the new output 
record. The new record is then inserted into the current "open" output record as- 
sociated with stream (or the top level output record if there is no currently "open" 
one). 

If record is supplied, it is the name of a variable that will be lexically bound to 
the new output record inside of body, init-args are initialization arguments that 
are passed to closrmake-instance when the new output record is created. 

clim:with-new-output-record returns the output record it creates. 

See the section "Concepts of CLIM Output Recording". 



clim:with-output-as-gadget (stream &rest options) &body body Macro 

Evaluates body to create a gadget, creates a gadget output record containing the 
gadget, and installs the output record into the output history of the stream. The 
returned value of body must be the gadget. 
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The options in options are passed as CLOS initargs to the call to climrinvoke- 
with-new-output-record that is used to create the gadget output record. 

For example, the following could be used to create an output record containing a 
radio box that itself contains several toggle buttons: 

(cl im:with-output-as-gadget (stream) 
(let* ((radio-box 

(cl im: make-pane 'cl im: radio-box 
:client stream :id 'radio-box))) 
(dolist (item sequence) 

(cl im: make-pane 'cl im: toggle-button 

:label (princ-to-string (item-name item)) 
: value (item-value item) 
:id item :parent radio-box)) 
radio-box)) 

A more complex (and somewhat contrived) example of a push button that calls 
back into the presentation type system to execute a command might be as follows: 

(cl im:with-output-as-gadget (stream) 
(cl im: make-pane 'cl im: push-button 
:label "Click here to exit" 
: acti vate-cal 1 back 
it' (lambda (button) 

(declare (ignore button)) 

(cl im: th row-high 1 ighted-presentation 

(make- instance 'cl im: standard-presentation 
:object ' (corn-exit ,cl im:*appl ication-framex) 
:type 'command) 
cl im:*input-contextx 

(make- instance 'cl im: pointer-button-press-event 
: sheet (cl im: sheet-parent button) 
:x :y 
modifiers 
: button cl im:+pointer-left-button+))))) 



clim:with-output-as-presentation (stream object type &key .-modifier :single-box (:al- 
low-sensitive-inferiors t) .-parent .-record-type) &body body Macro 

Gives separate access to the two aspects of climrpresent: recording the presenta- 
tion and drawing the visual representation. This macro generates a presentation 
from the output done in the body to the stream. The presentation's underlying ob- 
ject is object, and its presentation type is type. For information on the syntax of 
specifying a presentation type, see the section "How to Specify a CLIM Presenta- 
tion Type". 

All arguments of this macro are evaluated. 

clim:with-output-as-presentation returns a presentation. 
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Note that CLIM captures the presentation type for its own use, so you should not 
modify it once you have handed it to CLIM. 

Each invocation of this macro results in the creation of a presentation object in 
the stream's output history unless output recording has been disabled or rallow- 
sensitive-inferiors nil was specified at a higher level, in which case the presenta- 
tion object is not inserted into the history. 

For background information, see the section "Presentation Types in CLIM". 

stream 

The stream to which output should be sent. The default is 
*standard-output*. 

.■modifier 

Specifies a function of one argument (the new value) that can 
be called in order to store a new value for object after the user 
edits the presentation. The default is nil. 

:single-box Controls how CLIM determines whether the pointer is pointing 

at this presentation and controls how this presentation is high- 
lighted when it is sensitive. 

The possible values are: 

t If the pointer's position is inside the bound- 

ing rectangle of this presentation, it is con- 
sidered to be pointing at this presentation. 
This presentation is highlighted by highlight- 
ing its bounding rectangle. 

nil If the pointer is pointing at a visible piece of 

output (text or graphics) drawn as part of the 
visual representation of this presentation, it 
is considered to be pointing at this presenta- 
tion. This presentation is highlighted by high- 
lighting every visible piece of output that is 
drawn as part of its visual representation. 
This is the default. 

rposition Like t for determining whether the pointer is 

pointing at this presentation, like nil for 
highlighting. 

rhighlighting Like nil for determining whether the pointer 
is pointing at this presentation, like t for 
highlighting. 

Supplying :single-box rhighlighting is useful when the default 
behavior produces an ugly appearance (for example, a very 
jagged highlighting box). 
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Supplying :single-box rposition is useful when the visual rep- 
resentation of a presentation consists of one or more small 
graphical objects with a lot of space between them. In this 
case the default behavior offers only small targets that the 
user might find difficult to position the pointer over. 

:allow-sensitive-inferiors 

When :allow-sensitive-inferiors is nil, it indicates that nested 
calls to climrpresent or clim:with-output-as-presentation in- 
side this one should not generate presentations. The default is 
t. 



■.record-type 



This option is useful when you have defined a customized 
record type to replace CLIM's default record type. It specifies 
the class of the output record to be created. 



climrwith-output-recording-options (stream &key :draw .-record) &body body Macro 

Used to disable output recording and/or drawing on the given stream, within the 
extent of body. 

If :draw is nil, output to the stream is not drawn on the viewport, but can still be 
recorded in the output history. If -.record is nil, output recording is disabled but 
output otherwise proceeds normally. 



clim:with-output-to-output-record (stream &optional record-type record &rest ini- 
targs) &body body Macro 

This is similar to clim:with-new-output-record except that the new output record 
is not inserted into the output record hierarchy. That is, when you use climrwith- 
output-to-output-record no drawing on the stream occurs and nothing is put into 
the stream's normal output history. Unlike in facilities such as with-output-to- 
string, stream must be an actual stream, but no output will be done to it. 

record-type is the type of output record to create, which defaults to CLIM's default 
output record type, init-args are CLOS init keywords which are used to initialize 
the record. 

If record is supplied, it is a variable which will be bound to the new output record 
while body is evaluated. 

See the section "Concepts of CLIM Output Recording". 



clim:with-output-to-pixmap (medium-var medium &key .-width .-height) &body body 

Macro 

Binds medium-var to a "pixmap medium", that is, a medium that does output to a 
pixmap with the characteristics appropriate to the medium medium, and then eval- 
uates body in that context. All the output done to the medium designated by medi- 
um-var inside of body is drawn on the pixmap stream. 
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In Genera, you may call stream output functions (such as write-char and write- 
string) from within body, but not all CLIM implementations will necessarily sup- 
port this. 

.-width and .-height are integers that give the width and height of the pixmap. If 
they are unsupplied, the result pixmap will be just large enough to contain all of 
the output done by body. 

medium-var must be a symbol; it is not evaluated. 

The returned value is a pixmap that can be drawn onto medium using climrcopy- 
from-pixmap. 



clim:with-output-to-postscript-stream (stream-var file-stream &key -.device-type 
(-.orientation rportrait) -.multi-page : scale-to- fit .-header-comments (.-destination 
rprinter)) &body body Macro 

Within body, stream-var is bound to a stream that produces PostScript code. This 
stream is suitable as a stream or medium argument to any CLIM output utility. A 
PostScript program describing the output to the stream-var stream will be written 
to file-stream. 



.-device-type 



.-orientation 



.-multi-page 



: scale-to- fit 



.-header-comments 



The class of PostScript display device to use. The only device 
class currently provided is is suitable for generating PostScript 
for the printers such as the Apple LaserWriter. 

Specifies the orientation (portrait or landscape) of the output. 
It can be either rportrait or landscape. The default is 
rportrait. 

When supplied as t, any output that is larger than the size of 
a page will automatically be broken up into several pages. (No 
hints are given as to how the resulting pages should be pieced 
together; you're on your own here.) This defaults to nil. 

When supplied as t, this causes the output to be scaled so that 
it fits on a single page. This defaults to nil. It does not make 
sense to supply both .-multi-page and : scale-to- fit. 

This allows you to specify some PostScript header comment 
fields for the resulting PostScript program. The argument 
should be a list of alternating keyword and value pairs. These 
are the supported keywords: 



rtitle 



rfor 



Specifies a title for the document, as it will 
appear in the "%%Title:" header comment. 

Specifies who the document is for. The as- 
sociated value will appear in a "%%For:" 
document comment. 
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.■destination One of either rprinter or rdocument. When it is rprinter, the 

output file will include a PostScript "showpage" command that 
causes the output to be sent to the printer. When it is 
rdocument, the "showpage" command will not be included in 
the output file, making it suitable for inclusion in other docu- 
ments. 

See the section "Hardcopy Streams in CLIM". 

Note: The PostScript programs written by this implementation do not conform 
to the conventions described under "Appendix C: Structuring Conven- 
tions" of the PostScript Language Reference Manual. Software tools which 
attempt to determine information about these PostScript programs based 
on "%%" comments within them will be unsuccessful. 



clim:with-presentation-type-decoded (name-var &optional parameters-var options- 
var) type &body body Macro 

The specified variables are bound to the components of the presentation type spec- 
ifier, the forms in body are evaluated, and the values of the last form are re- 
turned. The value of the type must be a presentation type specifier, name-var, if 
non-nil, is bound to the presentation type name, parameters-var, if present and 
non-nil, is bound to a list of the parameters, options-var, if present and non-nil, is 
bound to a list of the options. 



clim:with-presentation-type-options (type-name type) &body body Macro 

Variables with the same name as each option in the definition of the presentation 
type are bound to the option values in type, if present, or else to the defaults spec- 
ified in the definition of the presentation type. The forms in body are evaluated in 
the scope of these variables and the values of the last form are returned. 

The value of the form type must be a presentation type specifier whose name is 
type-name, type-name is not evaluated. 



clim:with-presentation-type-parameters (type-name type) &body body Macro 

Variables with the same name as each parameter in the definition of the presenta- 
tion type are bound to the parameter values in type, if present, or else to the de- 
faults specified in the definition of the presentation type. The value of the form 
type must be a presentation type specifier whose name is type-name, type-name is 
not evaluated. The forms in body are evaluated in the scope of these variables and 
the values of the last form are returned. 



clim:with-radio-box f&rest options &key (:type 'rone-ofj &allow-other-keysJ &body 
body Macro 
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Creates a radio box or a check box whose buttons are created by the forms in 
body. The macro clim:radio-box-current-selection (or clim:check-box-current- 

selection) can be wrapped around one of forms in body in order to indicate that 
that button is the current selection. If :type is :one-of, this macro creates a radio 
box. If :type is :some-of, it creates a check box. 

See the section "Using Gadgets in CLIM". 

For example, the following creates a radio box with three buttons in it, the second 
of which is initially selected. 

(cl im:with-radio-box () 

(cl im: make-pane 'cl im: toggle-button :label "Mono") 
(cl im: radio-box-current-selection 

(cl im: make-pane 'cl im: toggle-button :label "Stereo")) 
(cl im:make-pane 'cl im: toggle-button :label "Quad")) 

The following simpler form can also be used when you do not need to control the 
appearance of each button closely: 

(cl im:with-radio-box () 
"Mono" "Stereo" "Quad") 



clim-sys:with-recursive-lock-held (place &optional state) &body forms Macro 

Evaluates body while holding the recursive lock named by place, place is a refer- 
ence to a recursive lock created by clim-sys:make-recursive-lock. 

On systems that do not support locking, clim-sys:with-recursive-lock-held is 
equivalent to progn. 

See the section "Locks in CLIM". 



clim:with-room-for-graphics f&optional stream &key .-height (-first-quadrant t) 
(■.move-cursor t) :record-type) &body body Macro 

Binds the dynamic environment to establish a local coordinate system for doing 
graphics output onto stream, body is evaluated to produce the output. 

If :first-quadrant is t (the default), a local Cartesian coordinate system is estab- 
lished with the origin (0,0) of the local coordinate system placed at the current 
cursor position; (0,0) is in the lower left corner of the area created. 

If -.move-cursor is t (the default), then after the graphic output is completed, the 
cursor is positioned past (immediately below) this origin. The bottom of the verti- 
cal block allocated is at this location (that is, just below point (0,0), not necessarily 
at the bottom of the output done). 

If -.height is supplied, it should be a number that specifies the amount of vertical 
space to allocate for the output, in device units. If it is not supplied, the height is 
computed from the output. 
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■.record-type specifies the class of output record to create to hold the graphical out- 
put. The default is climrstandard-sequence-output-record. 



climrwith-rotation (medium angle &optional origin) &body body Macro 

Establishes a rotation on medium that rotates clockwise by angle (in radians), and 
then evaluates body with that transformation in effect. If origin is supplied, the ro- 
tation is about that point. The default for origin is (0,0). 

This is equivalent to using climrwith-drawing-options with the rtransformation 
keyword argument supplied: 

(cl im:with-drawing-options 
(medium : transformation 

(cl im: make-rotation-transformation angle origin)) 
body) 



climrwith-scaling (medium sx &optional sy) &body body Macro 

Establishes a scaling transformation on medium that scales by sx in the X direc- 
tion and sy in the Y direction, and then evaluates body with that transformation in 
effect. If sy is not supplied, it defaults to sx. 

This is equivalent to using climrwith-drawing-options with the rtransformation 
keyword argument supplied: 

(cl im:with-drawing-options 
(medium : transformation 

(cl im:make-scal ing-transformation sx sy)) 
body) 



climrwith-sheet-medium (medium sheet) &body body Macro 

Within the body, the variable medium is bound to sheet's medium. If the sheet 
does not have a medium permanently allocated, one will be allocated, associated 
with the sheet for the duration of the body, and deallocated as the when the body 
has been exited. The values of the last form of the body are returned as the val- 
ues of climrsheet-medium. 

The medium argument is not evaluated, and must be a symbol that is bound to a 
medium. 

See the section "Sheet Output Protocols". 



climrwith-text-face (medium face) &body body Macro 

Binds the current text face of medium to correspond to the new text face face, 
within the body, face is one of rroman, rbold, ritalic, (rbold ritalic), or nil. The de- 
fault for medium is *standard-output*. 
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This is the same as: 

(cl im:with-drawing-options (medium -. text-face face) 
body) 

Using clim:with-text-family affects clim:medium-text-style. 

See the section "CLIM Text Style Objects". 

clim:with-text-family (medium family) &body body Macro 

Binds the current text family of medium to correspond to the new text family fam- 
ily, within the body, family is one of :fix, rserif, :sans-serif, or nil. The default for 
medium is *standard-output*. 

This is the same as: 

(cl im:with-drawing-options (medium : text-family family) 
body) 

Using clim:with-text-family affects clim:medium-text-style. 

See the section "CLIM Text Style Objects". 

clim:with-text-size (medium size) &body body Macro 

Binds the current text size of medium to correspond to the new size text size, 
within the body, size is one of the logical sizes (rnormal, rsmall, rlarge, :very- 
small, :very-large, rsmaller, rlarger), or a real number representing the size in 
printer's points, or nil. The default for medium is *standard-output*. 

This is the same as: 

(cl im:with-drawing-options (medium -. text-size size) 
body) 

Using clim:with-text-size affects clim:medium-text-style. 

See the section "CLIM Text Style Objects". 

clim:with-text-style (medium style) &body body Macro 

Binds the current text style of medium to correspond to the new text style, within 
the body, style is a text style object. The default for medium is *standard-output*. 

This is the same as: 

(cl im:with-drawing-options (medium -. text-styl e style) 
body) 

Using clim:with-text-style affects clim:medium-text-style. 

See the section "CLIM Text Style Objects". 



Page 1694 



climrwith-translation (medium dx dy) &body body Macro 

Establishes a scaling transformation on medium that scales by dx in the X direc- 
tion and dy in the Y direction, and then evaluates body with that transformation 
in effect. 

This is equivalent to using climrwith-drawing-options with the rtransformation 
keyword argument supplied: 

(cl im:with-drawing-options 
(medium : transformation 

(cl im:make-translation-transformation dx dy)) 
body) 



clim-sys:without-scheduling &body forms Macro 

Evaluates body in a context that is guaranteed to be free from interruption by oth- 
er processes. This returns the value of the last form in body. 

On systems that do not support multi-processing, clim-sys:without-scheduling is 
equivalent to progn. 



clim:write-token token stream &key .-acceptably Function 

clim:write-token is the opposite of clim:read-token: given the string token, it 
writes it to the stream stream. If .-acceptably is t and there are any characters in 
token that are delimiter gestures (see the macro climrwith-delimiter-gestures), 
then clim:write-token will surround the token with quotation marks, tt\". 

It is appropriate to use clim:write-token instead of write-string inside of 
climrpresent methods. 



CLIM Glossary 



Glossary of CLIM Terminology 

adopted (of a sheet) A sheet is said to be adopted when it has a parent 

sheet. 

affine transformation 

See transformation. 

ancestors The parent of a sheet or an output record, and all of the ances- 

tors of the parent, recursively. 

applicable (of a presentation translator) A presentation translator is said to 

be applicable when the pointer is pointing to a presentation 
whose presentation type matches the current input context, and 
the other criteria for translator matching have been met. 
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application frame In general, a program that interacts directly with a user to 
perform some specific task. In CLIM, a frame is the central 
mechanism for presenting an application's user interface. Also, 
a Lisp object that holds the information associated with such a 
program, including the panes of the user interface and applica- 
tion state variables. 

background The design that is used when erasing, that is, drawing on a 

medium using clim:+background-ink+. 

bounding rectangle 

The smallest rectangle that surrounds a bounded region and 
contains every point in the region; it may contain additional 
points as well. The sides of a bounding rectangle are parallel 
to the coordinate axes. Also, a Lisp object that represents a 
bounding rectangle. 

coordinates A pair of real numbers that identify a point in the drawing 

plane. 

cache value During incremental redisplay, CLIM uses the cache value to de- 

termine whether or not a piece of output has changed. 

children (of a sheet or output record) The direct descendants of a sheet 

or an output record. 

color An object representing the intuitive definition of a color, such 

as black or red. Also, a Lisp object that represents a color. See 
also ink. 

command An object that represents a user interaction. Each command 

has a name, which is a symbol. A command can also have ar- 
guments, both positional and keyword arguments. A user may 
enter a command in several different ways, by typing, by using 
a menu, or by directly clicking the mouse on some output. Al- 
so, a Lisp object that represents a command; a cons of the 
command name and the list of the command's arguments. 

command-defining macro 

A Lisp macro for defining the commands specific to a particu- 
lar application frame, defined by CLIM when the application 
frame is defined. 

command-line name 

The name that the end user sees and uses during command 
line interactions. This is not the same thing as the command 
name. For example, the command com-show-chart might have 
a command-line name of "Show Chart". 

command name A symbol that names a CLIM command. 

command parser The part of CLIM's command loop that performs the conver- 
sion of strings of characters (usually what the user typed) into 
a command. 
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command table 

completion 
compositing 

composition 



A way of collecting and organizing a group of related com- 
mands, and defining the interaction styles that can be used to 
invoke those commands. Also, a Lisp object that represents a 
command table. 

A facility provided by CLIM for completing user input from a 
set of possibilities. 

(of designs) The creation of a new design whose appearance at 
each point is a composite of the appearances of two other de- 
signs at that point. There are three varieties of compositing: 
composing over, composing in, and composing out. 

(of transformations) The transformation from one coordinate 
system to another, then from the second to a third can be rep- 
resented by a single transformation that is the composition of 
the two component transformations. Transformations are closed 
under composition. Composition is not commutative. Any arbi- 
trary transformation can be built up by composing a number of 
simpler transformations, but that composition is not unique. 

context sensitive input 

The facility in CLIM that allows an interface to describe what 
sort of input it expects by specifying the input's type. That 
type is called a presentation type. 

cursor The place in the drawing plane of a stream where the next 

piece of text output will appear. 

degrafted (of a sheet) Not grafted, that is, not attached to any display 

server. 

descendants All of the children of a sheet or an output record, and all of 

their descendants, recursively. 

design An object that represents a way of arranging colors and opaci- 

ties in the drawing plane. A mapping from an (x,y) pair into 
color and opacity values. A design is the generalization of a re- 
gion into the color domain. 

direct manipulation 

A style of interaction with an application where the user indi- 
cates the desired task by performing an analogous action in 
the interface. For instance, deleting a file by dragging an icon 
representing the file over another icon that looks like a trash 
can, or connecting two components in a circuit simulation by 
drawing a line representing a connection between two icons 
representing the components. 



disabled 
disowned 



(of a sheet) Not enabled. 

(of a sheet) Not adopted, that is, not having any parent sheet. 
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display function The function, associated with a particular pane in an applica- 
tion frame, that performs the "appropriate" output for that 
pane. 

A device on which output can appear, such as an X console or 
a PostScript printer. 

displayed output record 

An output record that corresponds to a visible piece of output, 
such as text or graphics. A leaf in an output record tree. 



display server 



drawing plane 



enabled 



event 



flipping ink 



foreground 



An imaginary two-dimensional plane, on which graphical output 
occurs, that extends infinitely in all directions and has infinite 
resolution. A drawing plane contains an arrangement of colors 
and opacities that is modified by each graphical output opera- 
tion. The drawing plane provides an idealized version of the 
graphics you draw. CLIM transfers the graphics from the 
drawing plane to a host window by a process called rendering. 

(of a sheet) A sheet is said to be enabled when it is actively 
participating in the windowing relationship with its parent. 

Some sort of significant event, such as a user gesture (such as 
moving the pointer, pressing a pointer button, or typing a 
keystroke) or a window configuration event (such as resizing a 
window). Also, a Lisp object that represents an event. 

An ink that interchanges occurrences of two designs, such as 
might be done by "XOR" on a monochrome display. Also, a 
Lisp object that represents a flipping ink. 

The design that is used when drawing on a medium using 
clim:+foreground-ink+. 



formatted output Output that obeys some high level constraints on its appear- 
ance, such as being arranged in a tabular format, or justified 
within some margins. The CLIM facility that provides a pro- 
grammer the tools to produce such output. 



frame 

frame manager 



fully specified 



gesture 



See application frame. 

An object associated with a port that controls the realization of 
the look and feel of an application frame. It is responsible for 
creating panes and gadgets, laying out menus and dialogs, and 
doing other tasks related to look and feel. 

(of a text style) Having components none of which are nil, and 
not having a relative size (that is, neither : smaller nor 
rlarger). 

Some sort of input action by a user, such as typing a character 
or clicking a pointer button. User gestures are frequently rep- 
resented by event objects. 
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gesture name A symbol that gives a name to a class of gestures, for example, 

rselect is commonly used to indicate a left pointer button click. 



gesture spec 



graft 



grafted 



highlighted 



A platform-independent way of specifying some sort of input 
gesture, such as a pointer button press or a key press. For ex- 
ample, the control -D "character" is specified by the gesture 
spec (:D : control). 

A kind of mirrored sheet that represents a host window, typi- 
cally a "root" window. 

(of a sheet) Having an ancestor sheet that is a graft. A grafted 
sheet will be visible on a display server, unless it is clipped or 
occluded by some other window on the same display. 

A visual indication that the presentation under the pointer is 
sensitive, and can thus be entered as input to the program cur- 
rently accepting input. Highlighting might appear as a box 
drawn around the presentation, or as a different appearance of 
the presentation, such as a bold text style. 

incremental redisplay 

The redrawing of part of some output while leaving other out- 
put unchanged. The CLIM facility that implements this behav- 
ior. 

An ink whose exact behavior depends on the context in which 
it is used. Drawing with an indirect ink is the same as draw- 
ing with another ink named directly. clim:+foreground-ink+ 
and clim:+background-ink+ are both indirect inks. 

Any member of the class design supplied as the rink argument 
to a CLIM drawing function. 

A state in which a program is expecting input of a certain 
type. A command that takes arguments as input specifies the 
presentation type of each argument. When the command is 
given, an input context is set up in which presentations that 
are appropriate are sensitive (they are highlighted when the 
pointer passes over them). Also, a Lisp object that represents 
an input context. 

The CLIM facility that allows a user to modify typed-in input. 



indirect ink 



ink 



input context 



input editor 



input editing stream 

A CLIM stream that supports input editing. 

interactive stream A stream that supports both input from and output to the user 
in an interactive fashion. 

keyboard accelerator 

A single key or key chord (that is, set of keys pressed togeth- 
er) used to issue an entire command. 
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line style 



medium 



mirror 



Advice to CLIM's rendering substrate on how to draw a path, 
such as a line or an unfilled ellipse or polygon. Also, a Lisp ob- 
ject that represents a line style. 

A destination for output, having a drawing surface, two designs 
called the medium's foreground and background, a transforma- 
tion, a clipping region, a line style, and a text style. Also, a Lisp 
object that represents a medium. 

The host window system object associated with a mirrored 
sheet, such as a window on Genera or an Xll display server. 

A special class of sheet that is attached directly to a window on 
a display server. A graft is one kind of a mirrored sheet. On 
some platforms, many of the gadgets (such as scroll bars and 
push buttons) will be mirrored sheets as well. 

mixed mode interface 

An interface to an application that allows more than one style 
or mode of interaction. For example a user might be able to 
enter the same command by typing it, by clicking on a menu 
button, or by dragging an icon. 



mirrored sheet 



opacity 



output history 
output record 



A way of controlling how new graphical output covers previous 
output, such as fully opaque to fully transparent, and levels of 
translucency between. Also, a Lisp object that represents an 
opacity. 

The highest level output record for an output recording stream. 

An object that remembers the output performed to an output 
recording stream. Also, a Lisp object that represents an output 
record. 



output recording The process of remembering the output performed to a stream. 
Output recording is the basis for other CLIM facilities, such as 
formatted output, incremental redisplay, and context-sensitive 
input. 

output recording stream 

A CLIM stream that remembers and can replay its output. 

pane A sheet or window that appears as the child of some other win- 

dow or frame. A composite pane can hold other panes; a leaf 
pane cannot. An application frame is normally composed of a 
hierarchy of panes. 

parameterized presentation type 

A presentation type whose semantics are modified by parame- 
ters. A parameterized presentation type is always a subtype of 
the presentation type without parameters. For example, 
(integer 10) is a parameterized type indicating an integer in 
the range of zero to ten. Parameterized presentation types are 
analogous to Common Lisp types that have parameters. 



Page 1700 



parent 
patterning 

pixmap 

point 

pointer 



The direct ancestor of a sheet or an output record. 

The process of creating a bounded rectangular arrangement of 
designs, like a checkerboard. A pattern is a design created by 
this process. 

An "off-screen window", that is, an object that can be used for 
graphical output, but is not visible on any display device. 

A region that has dimensionality 0, that is, has only a position. 
Also, a Lisp object that represents a point. 

An input device that enables pointing to an area of the screen, 
such as a mouse, tablet, or other pointing device. 



pointer documentation 

Short documentation associated with a presentation that de- 
scribes what will happen when any button on the pointer is 
pressed. 



port 



position 



presentation 



A connection to a display server that is responsible for manag- 
ing host display server resources and for processing input 
events received from the host display server. 

A location on a plane, such as CLIM's abstract drawing plane. 
A pair of real number values (x,y) that represent a position. 

An association between an object and a presentation type with 
some output on an output recording stream. Also, a Lisp object 
that represents a presentation, consisting of at least three 
things: the underlying application object, its presentation type, 
and its displayed appearance. 

presentation method 

A method that supports some part of the behavior of a presen- 
tation type, such as the climraccept method (which parses key- 
board input into an object of this type) and the climrpresent 
method (which displays the object as a presentation which will 
be sensitive in matching contexts). 

presentation testerA predicate that restricts the applicability of a presentation 
translator. It is used only to prevent a translation that would 
otherwise happen. 

presentation-to-command translator 

A particular type of presentation translator where the "to type" 
(that is, the type of presentation resulting from the transla- 
tion) is a command. 

presentation translator 

A mapping from an object of one presentation type, an input 
context, and a gesture to an object of another presentation type. 
In effect, a translator broadens an input context so that some 
presentations are sensitive when the program seeking input is 
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expecting a different type. A presentation translator enables 
the user to enter a presentation of a related type which can be 
translated into input of the expected type. 

presentation type A description of a class of presentations. The semantic type of 
an object to be displayed to the user. 

presentation type specifier 

The syntax for specifying a presentation type to CLIM func- 
tions such as climraccept, climrpresent, and others. There are 
three patterns for specifying presentation types, the first being 
simply its name, and the other two enabling you to specify its 
parameters and options. 



programmer 
rectangle 

redisplay 
region 



rendering 



repainting 

replaying 
sensitive 



sheet 



sheet region 



A person who writes application programs using CLIM. 

A four-sided polygon whose sides are parallel to the coordinate 
axes. Also, a Lisp object that represents a rectangle. 

See incremental redisplay. 

A set of mathematical points in the plane; a mapping from an 
(x,y) pair into either true or false (meaning member or not a 
member, respectively, of the region). In CLIM, all regions in- 
clude their boundaries (that is, they are closed) and have infi- 
nite resolution. Also, a Lisp object that represents a region. 

The process of drawing a shape (such as a line or a circle) on 
a display device. Rendering is an approximate process, since an 
abstract shape exists in a continuous coordinate system having 
infinite precision, whereas display devices must necessarily 
draw discrete points having some measurable size. 

The act of redrawing all of the sheets or output records in a 
"damage region", such as occurs when a window is raised 
from underneath occluding windows. 

The process of redrawing a set of output records. 

(of a presentation) Relevant to the current input context. A pre- 
sentation is sensitive if some action will take place when the 
user clicks on it with the pointer, that is, there is at least one 
presentation translator that is applicable. In this case, the pre- 
sentation will usually be highlighted. 

The basic unit of windowing in CLIM. A sheet's attributes al- 
ways include a region and a mapping to the coordinate system 
of its parent, and may include other attributes, such as a medi- 
um and event handling. Also, a Lisp object that represents a 
sheet. 

The region that a sheet occupies. 



sheet transformation 

A transformation that maps the coordinates of a sheet to the 
coordinate system of its parent, if it has a parent. 



Page 1702 



stream 
text face 
text family 



text size 
text style 



tiling 



top level sheet 



transformation 



unique id 



user 



view 



A kind of sheet that implements the stream protocol (such as 
doing textual input and output, and maintaining a text cursor). 

The component of a text style that specifies a variety or modifi- 
cation of a text family, such as bold or italic. 

The highest level component of a text style that specifies the 
common appearance of all the characters. Characters of the 
same family have a typographic integrity so that all characters 
of the same family resemble one another, such as :sans-serif. 

The component of a text style that specifies the size of text. 

A description of how textual output should appear, consisting 
of family, face code, and size. Also, a Lisp object that repre- 
sents a text style. 

The process of repeating a rectangular portion of a design 
throughout the drawing plane. A tile is a design created by this 
process. 

The single, topmost sheet associated with an entire application 
frame. All the panes of the frame are descendants of this 
sheet. 

A mapping from one coordinate system onto another that pre- 
serves straight lines. General transformations include all the 
sorts of transformations that CLIM uses, namely, translations, 
scaling, rotations, and reflections. Also, a Lisp object that rep- 
resents a transformation. 

During incremental redisplay, the unique id is an object used to 
uniquely identify a piece of output. The output named by the 
unique id will often have a cache value associated with it. 
When incremental redisplay finds a unique id that it has seen 
before and its cache value has changed since the last time re- 
display was done, then CLIM will redraw that piece of output. 

A person who uses an application program that was written us- 
ing CLIM. 

A way of displaying a presentation. Views can serve to mediate 
between presentations and gadgets. Also, a Lisp object that 
represents a view . 



viewport 



The region of the drawing plane that is visible on a window. 



